1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
=head1 NAME
rthread - Roy threading API
=head1 SYNOPSIS
#include <roy.h>
RThreadMutex rthread_mutex_new (void);
int rthread_mutex_lock (RThreadMutex mutex);
int rthread_mutex_trylock (RThreadMutex mutex);
int rthread_mutex_unlock (RThreadMutex mutex);
void rthread_mutex_destroy (RThreadMutex mutex);
RTHREAD_MUTEX_ENTER(mutex)
RTHREAD_MUTEX_EXIT(mutex)
=head1 DESCRIPTION
These functions add mutex support to the RThread API. Mutex stands
for mutual exclusion and allows only one thread at a time to enter
a peice of code protected by one. These are often used to protect
global and static variables and data structures from simultaneous
modification.
Mutex locking should always be balanced; that is, one lock for
every unlock. While this is not a requirement on many pthread
implementations, it is required on Win32.
The RTHREAD_MUTEX_ENTER/EXIT macros are to be used as a pair within a
single function and require opening and closing braces around the code
they are to protect. This gives a nice, forced balance to mutexes.
For example:
RTHREAD_MUTEX_ENTER(mutex) {
... code ...
} RTHREAD_MUTEX_EXIT(mutex);
rthread_mutex_new(3) initializes a mutex for use. Note the lack of a
pointer for this type. This is intentional as the type is defined
differently on different platforms. You must always declare the
mutex without a pointer.
rthread_mutex_lock(3) locks the mutex so that no other threads may
enter. This call may block until the previous thread has exited the
mutex (if necessary).
rthread_mutex_trylock(3) will not block if the mutex is in use and
will simply return non-zero in the event that the lock is already
in use.
rthread_mutex_unlock(3) will unlock a mutex allowing others to
enter.
rthread_mutex_destroy(3) will destroy a mutex and free any storage
associated with it.
=head1 RETURN VALUES
All functions returning an I<int> return 0 on success, or non-zero
on failure.
=head1 SEE ALSO
L<roy(3)|roy(3)>, L<rthread(3)|rthread(3)>,
L<rthread_event(3)|rthread_event(3)>
|
