Browse code

doc: reorganized the content of doc folder

Daniel-Constantin Mierla authored on 07/12/2016 13:54:42
Showing 1 changed files
1 1
deleted file mode 100644
... ...
@@ -1,181 +0,0 @@
1
-
2
-Kamailio locking interface
3
-============================
4
-
5
-1. Why use it?
6
-
7
-The main reason for creating it was to have a single transparent interface to various locking methods. 
8
-For example right now Kamailio uses the following locking methods, depending on their availability on the 
9
-target system:
10
-	FAST_LOCK - fast inline assembly locks, defined in fast_lock.h. They are currently available for 
11
-	x86, x86_64, sparc, sparc64, arm , armv6 (no smp mode supported yet), ppc, ppc64, mips, mips64 
12
-	and alpha . In general if the assembly code exists for a given arhitecture and the compiler 
13
-	knows inline assembly (for example sun cc does not) FAST_LOCK is prefered. The main 
14
-	advantage of using FAST_LOCK is very low memory overhead and extremely fast lock/unlock 
15
-	operations (like 20 times faster then SYSV semaphores on linux & 40 times on solaris). 
16
-	The only thing that comes close to them are pthread mutexes (which are about 3-4 times slower).
17
-
18
-	PTHREAD_MUTEX - uses pthread_mutex_lock/unlock. They are quite fast but they work between 
19
-	processes only on some systems (they do not work on linux).
20
-
21
-	POSIX_SEM  - uses posix semaphores (sem_wait/sem_post). They are slower then the previous 
22
-	methods but still way faster then SYSV sempahores. Unfortunately they also do not work on 
23
-	all the systems (e.g. linux).
24
-	
25
-	SYSV_SEM - this is the most portable but also the slowest locking method. Another problem is 
26
-	that the number of semaphores that can be alocated by a process is limited. One also has to 
27
-	free them before exiting.
28
-
29
-
30
-2. How to use it?
31
-
32
-First of all you have to include locking.h. Then when compiling the code one or all of FAST_LOCK, 
33
-USE_PTHREAD_MUTEX, USE_PTHREAD_SEM or USE_SYSV_SEM must be defined (the Kamailio Makefile.defs takes 
34
-care of this, you should need to change it only for new arhitectures or compilers).
35
-
36
-locking.h defines 2 new types: gen_lock_t and lock_set_t.
37
-
38
-
39
-3. Simple locks
40
-
41
-The simple locks are simple mutexes. The type is gen_lock_t.
42
-WARNING: do not make any assumptions on gen_lock_t base type, it does not have to be always an int.
43
-
44
-Allocation & initialization:
45
-
46
-The locks are allocated with:
47
-   gen_lock_t* lock_alloc();
48
-and initialized with:
49
-   gen_lock_t* lock_init(gen_lock_t* lock);
50
-
51
-Both function return 0 on failure.
52
-The locks must be initialized before use.
53
-
54
-A proper alloc/init sequence looks like:
55
-
56
-gen_lock_t* lock;
57
-
58
-lock=lock_alloc();
59
-if (lock==0) goto error;
60
-if (lock_init(lock)==0){
61
-   lock_dealloc(lock);
62
-   goto error; /* could not init lock*/
63
-}
64
-...
65
-
66
-Lock allocation can be skipped in some cases: if the lock is already in shared memory you don't need to
67
-allocate it again, you can initialize it directly, but keep in mind that the lock MUST be in shared memory.
68
-
69
-Example:
70
-
71
-struct s {
72
-    int foo;
73
-    gen_lock_t lock;
74
-} bar;
75
-
76
-bar=shm_malloc(sizeof struct s); /* we allocate it in the shared memory */
77
-if (lock_init(&bar->lock)==0){
78
- /* error initializing the lock */
79
- ...
80
-}
81
-
82
-
83
-Destroying & deallocating the locks:
84
-
85
-  void    lock_destroy(gen_lock_t* lock);
86
-  void    lock_dealloc(gen_lock_t* lock);
87
- 
88
-The lock_destroy function must be called first. It removes the resources associated with the 
89
-lock, but it does not also free the lock shared memory part. Think of sysv rmid.
90
-Please don't forget to call this function, or you can leave allocated resources in some cases 
91
-(e.g sysv semaphores). Be carefull to call it in your module destroy function if you use any 
92
-global module locks.
93
-
94
-Example:
95
-	lock_destroy(lock);
96
-	lock_dealloc(lock);
97
-
98
-Of course you don't need to call lock_dealloc if your lock was not allocated with lock_alloc.
99
-
100
-
101
-Locking & unlocking:
102
-
103
-void    lock_get(gen_lock_t* lock);      - lock (mutex down)
104
-void    lock_release(gen_lock_t* lock);  - unlock (mutex up)
105
-int     lock_try(gen_lock_t* lock);      - tries to lock and returns 0 
106
-                                           if succesfull, -1 if not (this is
107
-                                           a non-blocking lock_get())
108
-
109
-
110
-
111
-4. Lock Sets
112
-
113
-The lock sets are kind of sysv semaphore sets equivalent. The type is lock_set_t.
114
-Use them when you need a lot of mutexes. In some cases they waste less system 
115
-resources than arrays of gen_lock_t (e.g. sys v semaphores).
116
-
117
-Allocating & initializing:
118
-
119
-	lock_set_t* lock_set_alloc(int no);
120
-	lock_set_t* lock_set_init(lock_set_t* set);
121
-
122
-Both functions return 0 on failure.
123
-
124
-WARNING: expect the allocation function to fail for large numbers. It depends on the locking 
125
-method used & the system available resources (again the sysv semaphores example).
126
-
127
-Example:
128
-
129
-	lock_set_t *lock_set;
130
-
131
-	lock_set=lock_set_alloc(100);
132
-	if (lock_set==0) goto error;
133
-	if (lock_set_init(lock_set)==0){
134
-   		lock_set_dealloc(lock_set);
135
-   		goto error;
136
-	}
137
-
138
-or
139
- 	if ((lock_set=lock_set_alloc(100))==0) || (lock_set_init(lock_set)==0)){
140
-   		if (lock_set) lock_set_dealloc(lock_set);
141
-   		goto error;
142
- 	}
143
-
144
-
145
-Destroying & deallocating:
146
-  void lock_set_destroy(lock_set_t* s);
147
-  void lock_set_dealloc(lock_set_t* s);
148
-
149
-Again don't forget to "destroy" the locks.
150
-
151
-
152
-Locking & unlocking:
153
-
154
-void lock_set_get(lock_set_t* s, int i);
155
-void lock_set_release(lock_set_t* s, int i);
156
-int  lock_set_try(lock_set_t* s, int i);      - tries to lock the i-th lock
157
-                                                from the set. If succesfull
158
-                                                returns 0, if not -1.
159
-
160
-Example:
161
-
162
-lock_set_get(lock_set, 2);
163
-/* do something */
164
-lock_set_release(lock_set, 2);
165
-
166
-
167
-When to use lock_set_t & when to use gen_lock_t
168
-If you use lots of semaphores and GEN_LOCK_T_PREFERED is undefined then use
169
-lock_set_t. If GEN_LOCK_T_PREFERED is defined you can safely use gen_lock_t 
170
-arrays instead.
Browse code

doc Remove SVN ID's, remove history, change "SIP-router" and "ser" to "Kamailio"

Olle E. Johansson authored on 10/01/2015 08:47:18
Showing 1 changed files
... ...
@@ -1,19 +1,12 @@
1
-# $Id$
2
-#
3
-# History:
4
-#---------
5
-#  2003-03-11  created by andrei
6
-#  2006-04-04  minor archs updates, added lock_try(..)  (andrei)
7 1
 
8
-
9
-SIP-router locking interface
2
+Kamailio locking interface
10 3
 ============================
11 4
 
12 5
 1. Why use it?
13 6
 --------------
14 7
 
15 8
 The main reason for creating it was to have a single transparent interface to various locking methods. 
16
-For example right now SIP-router uses the following locking methods, depending on their availability on the 
9
+For example right now Kamailio uses the following locking methods, depending on their availability on the 
17 10
 target system:
18 11
 	FAST_LOCK - fast inline assembly locks, defined in fast_lock.h. They are currently available for 
19 12
 	x86, x86_64, sparc, sparc64, arm , armv6 (no smp mode supported yet), ppc, ppc64, mips, mips64 
... ...
@@ -39,7 +32,7 @@ target system:
39 32
 -----------------
40 33
 
41 34
 First of all you have to include locking.h. Then when compiling the code one or all of FAST_LOCK, 
42
-USE_PTHREAD_MUTEX, USE_PTHREAD_SEM or USE_SYSV_SEM must be defined (the SIP-router Makefile.defs takes 
35
+USE_PTHREAD_MUTEX, USE_PTHREAD_SEM or USE_SYSV_SEM must be defined (the Kamailio Makefile.defs takes 
43 36
 care of this, you should need to change it only for new arhitectures or compilers).
44 37
 
45 38
 locking.h defines 2 new types: gen_lock_t and lock_set_t.
Browse code

Formatting and doxygen documentation updates

oej authored on 21/10/2009 08:21:47
Showing 1 changed files
... ...
@@ -7,7 +7,7 @@
7 7
 
8 8
 
9 9
 SIP-router locking interface
10
-
10
+============================
11 11
 
12 12
 1. Why use it?
13 13
 --------------
Browse code

Documentation updates

- Including locking.txt in doxygen
- Updating other files (ser -> sip-router)

oej authored on 21/10/2009 08:09:03
Showing 1 changed files
... ...
@@ -6,23 +6,41 @@
6 6
 #  2006-04-04  minor archs updates, added lock_try(..)  (andrei)
7 7
 
8 8
 
9
-SER locking interface
9
+SIP-router locking interface
10 10
 
11 11
 
12 12
 1. Why use it?
13
-   ----------
14
-
15
- The main reason in creating it was to have a single transparent interface to various locking methods. For example right now ser uses the following locking methods, depending on their availability on the target system:
16
- FAST_LOCK - fast inline assembly locks, defined in fast_lock.h. They are currently available for x86, x86_64, sparc, sparc64, arm , armv6 (no smp mode supported yet), ppc, ppc64, mips, mips64 and alpha . In general if the assembly code exists for a given arhitecture and the compiler knows inline assembly (for example sun cc does not) FAST_LOCK is prefered. The main advantage of using FAST_LOCK is very low memory overhead and extremely fast lock/unlock operations (like 20 times faster then SYSV semaphores on linux & 40 times on solaris). The only thing that comes close to them are pthread mutexes (which are about 3-4 times slower).
17
- PTHREAD_MUTEX - uses pthread_mutex_lock/unlock. They are quite fast but they work between processes only on some systems (they do not work on linux).
18
- POSIX_SEM  - uses posix semaphores (sem_wait/sem_post). They are slower then the previous methods but still way faster then SYSV sempahores. Unfortunately they also do not work on all the systems (e.g. linux).
19
- SYSV_SEM - this is the most portable but also the slowest locking method. Another problem is that the number of semaphores that can be alocated by a process is limited. One also has to free them before exiting.
13
+--------------
14
+
15
+The main reason for creating it was to have a single transparent interface to various locking methods. 
16
+For example right now SIP-router uses the following locking methods, depending on their availability on the 
17
+target system:
18
+	FAST_LOCK - fast inline assembly locks, defined in fast_lock.h. They are currently available for 
19
+	x86, x86_64, sparc, sparc64, arm , armv6 (no smp mode supported yet), ppc, ppc64, mips, mips64 
20
+	and alpha . In general if the assembly code exists for a given arhitecture and the compiler 
21
+	knows inline assembly (for example sun cc does not) FAST_LOCK is prefered. The main 
22
+	advantage of using FAST_LOCK is very low memory overhead and extremely fast lock/unlock 
23
+	operations (like 20 times faster then SYSV semaphores on linux & 40 times on solaris). 
24
+	The only thing that comes close to them are pthread mutexes (which are about 3-4 times slower).
25
+
26
+	PTHREAD_MUTEX - uses pthread_mutex_lock/unlock. They are quite fast but they work between 
27
+	processes only on some systems (they do not work on linux).
28
+
29
+	POSIX_SEM  - uses posix semaphores (sem_wait/sem_post). They are slower then the previous 
30
+	methods but still way faster then SYSV sempahores. Unfortunately they also do not work on 
31
+	all the systems (e.g. linux).
32
+	
33
+	SYSV_SEM - this is the most portable but also the slowest locking method. Another problem is 
34
+	that the number of semaphores that can be alocated by a process is limited. One also has to 
35
+	free them before exiting.
20 36
 
21 37
 
22 38
 2. How to use it?
23 39
 -----------------
24 40
 
25
-First of all you have to include locking.h. Then when compiling the code one or all of FAST_LOCK, USE_PTHREAD_MUTEX, USE_PTHREAD_SEM or USE_SYSV_SEM must be defined (the ser Makefile.defs takes care of this, you should need to change it only for new arhitectures or compilers).
41
+First of all you have to include locking.h. Then when compiling the code one or all of FAST_LOCK, 
42
+USE_PTHREAD_MUTEX, USE_PTHREAD_SEM or USE_SYSV_SEM must be defined (the SIP-router Makefile.defs takes 
43
+care of this, you should need to change it only for new arhitectures or compilers).
26 44
 
27 45
 locking.h defines 2 new types: gen_lock_t and lock_set_t.
28 46
 
... ...
@@ -56,7 +74,8 @@ if (lock_init(lock)==0){
56 74
 }
57 75
 ...
58 76
 
59
-Lock allocation can be skipped in some cases: if the lock is already in shared memory you don't need to allocate it again, you can initialize it directly, but keep in mind that the lock MUST be in shared memory.
77
+Lock allocation can be skipped in some cases: if the lock is already in shared memory you don't need to
78
+allocate it again, you can initialize it directly, but keep in mind that the lock MUST be in shared memory.
60 79
 
61 80
 Example:
62 81
 
... ...
@@ -78,13 +97,15 @@ Destroying & deallocating the locks:
78 97
   void    lock_destroy(gen_lock_t* lock);
79 98
   void    lock_dealloc(gen_lock_t* lock);
80 99
  
81
- The lock_destroy function must be called first. It removes the resources associated with the lock, but it does not also free the lock shared memory part. Think of sysv rmid.
82
- Please don't forget to call this function, or you can leave allocated resources in some cases (e.g sysv semaphores). Be carefull to call it in your module destroy function if you use any global module locks.
100
+The lock_destroy function must be called first. It removes the resources associated with the 
101
+lock, but it does not also free the lock shared memory part. Think of sysv rmid.
102
+Please don't forget to call this function, or you can leave allocated resources in some cases 
103
+(e.g sysv semaphores). Be carefull to call it in your module destroy function if you use any 
104
+global module locks.
83 105
 
84 106
 Example:
85
-lock_destroy(lock);
86
-lock_dealloc(lock);
87
-
107
+	lock_destroy(lock);
108
+	lock_dealloc(lock);
88 109
 
89 110
 Of course you don't need to call lock_dealloc if your lock was not allocated with lock_alloc.
90 111
 
... ...
@@ -104,34 +125,36 @@ int     lock_try(gen_lock_t* lock);      - tries to lock and returns 0
104 125
 ------------
105 126
 
106 127
 The lock sets are kind of sysv semaphore sets equivalent. The type is lock_set_t.
107
-Use them when you need a lot of mutexes. In some cases they waste less system resources than arrays of gen_lock_t (e.g. sys v semaphores).
128
+Use them when you need a lot of mutexes. In some cases they waste less system 
129
+resources than arrays of gen_lock_t (e.g. sys v semaphores).
108 130
 
109 131
 Allocating & initializing:
110 132
 --------------------------
111 133
 
112
-lock_set_t* lock_set_alloc(int no);
113
-lock_set_t* lock_set_init(lock_set_t* set);
134
+	lock_set_t* lock_set_alloc(int no);
135
+	lock_set_t* lock_set_init(lock_set_t* set);
114 136
 
115 137
 Both functions return 0 on failure.
116 138
 
117
-WARNING: expect the allocation function to fail for large numbers. It depends on the locking method used & the system available resources (again the sysv semaphores example).
139
+WARNING: expect the allocation function to fail for large numbers. It depends on the locking 
140
+method used & the system available resources (again the sysv semaphores example).
118 141
 
119 142
 Example:
120 143
 
121
-lock_set_t *lock_set;
144
+	lock_set_t *lock_set;
122 145
 
123
-lock_set=lock_set_alloc(100);
124
-if (lock_set==0) goto error;
125
-if (lock_set_init(lock_set)==0){
126
-   lock_set_dealloc(lock_set);
127
-   goto error;
128
-}
146
+	lock_set=lock_set_alloc(100);
147
+	if (lock_set==0) goto error;
148
+	if (lock_set_init(lock_set)==0){
149
+   		lock_set_dealloc(lock_set);
150
+   		goto error;
151
+	}
129 152
 
130 153
 or
131
- if ((lock_set=lock_set_alloc(100))==0) || (lock_set_init(lock_set)==0)){
132
-   if (lock_set) lock_set_dealloc(lock_set);
133
-   goto error;
134
- }
154
+ 	if ((lock_set=lock_set_alloc(100))==0) || (lock_set_init(lock_set)==0)){
155
+   		if (lock_set) lock_set_dealloc(lock_set);
156
+   		goto error;
157
+ 	}
135 158
 
136 159
 
137 160
 Destroying & deallocating:
... ...
@@ -161,5 +184,5 @@ lock_set_release(lock_set, 2);
161 184
 When to use lock_set_t & when to use gen_lock_t
162 185
 -----------------------------------------------
163 186
 If you use lots of semaphores and GEN_LOCK_T_PREFERED is undefined then use
164
- lock_set_t. If GEN_LOCK_T_PREFERED is defined you can safely use gen_lock_t 
165
- arrays instead.
187
+lock_set_t. If GEN_LOCK_T_PREFERED is defined you can safely use gen_lock_t 
188
+arrays instead.
Browse code

- fastlock: optimizations (in general a "nicer" spin on the lock for the other cpus) and cleanups for sparc, sparc64, armv6 (nosmp for now), ppc*, mips* - fastlock: alpha: replace the cond. jump backward with a cond. jump forward and then jump backward (because a cond. jump with a negative relative offset is always predicted as taken and we want it to be predicted as not taken) - fastlock: sparc (32) smp support - lock_ops.h: introduced lock_try and lock_set_try (non-blocking lock_*_get versions, returns -1 if it failed to get the lock and 0 if it succeeds), for all the supported locking methods (fast_lock, pthread_mutex, posix_sem, sysv_sems) - updated locking doc.

Andrei Pelinescu-Onciul authored on 04/04/2006 18:04:01
Showing 1 changed files
... ...
@@ -3,6 +3,7 @@
3 3
 # History:
4 4
 #---------
5 5
 #  2003-03-11  created by andrei
6
+#  2006-04-04  minor archs updates, added lock_try(..)  (andrei)
6 7
 
7 8
 
8 9
 SER locking interface
... ...
@@ -12,9 +13,9 @@ SER locking interface
12 13
    ----------
13 14
 
14 15
  The main reason in creating it was to have a single transparent interface to various locking methods. For example right now ser uses the following locking methods, depending on their availability on the target system:
15
- FAST_LOCK - fast inline assembly locks, defined in fast_lock.h. They are currently available for x86, sparc64, strongarm (amv4l) and ppc (external untested contributed code). In general if the assembly code exists for a given arhitecture and the compiler knows inline assembly (for example sun cc does not) FAST_LOCK is prefered. The main advantage of using FAST_LOCK is very low memory overhead and extremely fast lock/unlock operations (like 20 times faster then SYSV semaphores on linux & 40 times on solaris). The only thing that comes close to them are pthread mutexes (which are about 3-4 times slower).
16
+ FAST_LOCK - fast inline assembly locks, defined in fast_lock.h. They are currently available for x86, x86_64, sparc, sparc64, arm , armv6 (no smp mode supported yet), ppc, ppc64, mips, mips64 and alpha . In general if the assembly code exists for a given arhitecture and the compiler knows inline assembly (for example sun cc does not) FAST_LOCK is prefered. The main advantage of using FAST_LOCK is very low memory overhead and extremely fast lock/unlock operations (like 20 times faster then SYSV semaphores on linux & 40 times on solaris). The only thing that comes close to them are pthread mutexes (which are about 3-4 times slower).
16 17
  PTHREAD_MUTEX - uses pthread_mutex_lock/unlock. They are quite fast but they work between processes only on some systems (they do not work on linux).
17
- POSIX_SEM  - uses posix semaphores (sem_wait/sem_post). They are slower then the previous methods but still way faster then SYSV sempahores. Unfortunately they also do not work  on all the systems (e.g. linux).
18
+ POSIX_SEM  - uses posix semaphores (sem_wait/sem_post). They are slower then the previous methods but still way faster then SYSV sempahores. Unfortunately they also do not work on all the systems (e.g. linux).
18 19
  SYSV_SEM - this is the most portable but also the slowest locking method. Another problem is that the number of semaphores that can be alocated by a process is limited. One also has to free them before exiting.
19 20
 
20 21
 
... ...
@@ -93,6 +94,9 @@ Locking & unlocking:
93 94
 
94 95
 void    lock_get(gen_lock_t* lock);      - lock (mutex down)
95 96
 void    lock_release(gen_lock_t* lock);  - unlock (mutex up)
97
+int     lock_try(gen_lock_t* lock);      - tries to lock and returns 0 
98
+                                           if succesfull, -1 if not (this is
99
+                                           a non-blocking lock_get())
96 100
 
97 101
 
98 102
 
... ...
@@ -143,6 +147,9 @@ Locking & unlocking:
143 147
 
144 148
 void lock_set_get(lock_set_t* s, int i);
145 149
 void lock_set_release(lock_set_t* s, int i);
150
+int  lock_set_try(lock_set_t* s, int i);      - tries to lock the i-th lock
151
+                                                from the set. If succesfull
152
+                                                returns 0, if not -1.
146 153
 
147 154
 Example:
148 155
 
Browse code

-.minor updates

Andrei Pelinescu-Onciul authored on 17/03/2003 18:41:27
Showing 1 changed files
... ...
@@ -123,6 +123,12 @@ if (lock_set_init(lock_set)==0){
123 123
    goto error;
124 124
 }
125 125
 
126
+or
127
+ if ((lock_set=lock_set_alloc(100))==0) || (lock_set_init(lock_set)==0)){
128
+   if (lock_set) lock_set_dealloc(lock_set);
129
+   goto error;
130
+ }
131
+
126 132
 
127 133
 Destroying & deallocating:
128 134
 --------------------------
... ...
@@ -145,3 +151,8 @@ lock_set_get(lock_set, 2);
145 151
 lock_set_release(lock_set, 2);
146 152
 
147 153
 
154
+When to use lock_set_t & when to use gen_lock_t
155
+-----------------------------------------------
156
+If you use lots of semaphores and GEN_LOCK_T_PREFERED is undefined then use
157
+ lock_set_t. If GEN_LOCK_T_PREFERED is defined you can safely use gen_lock_t 
158
+ arrays instead.
Browse code

- Makefile bug fixed (LOCALBASE not exported) - minor locking.h beautifications

Andrei Pelinescu-Onciul authored on 12/03/2003 12:56:36
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,147 @@
1
+# $Id$
2
+#
3
+# History:
4
+#---------
5
+#  2003-03-11  created by andrei
6
+
7
+
8
+SER locking interface
9
+
10
+
11
+1. Why use it?
12
+   ----------
13
+
14
+ The main reason in creating it was to have a single transparent interface to various locking methods. For example right now ser uses the following locking methods, depending on their availability on the target system:
15
+ FAST_LOCK - fast inline assembly locks, defined in fast_lock.h. They are currently available for x86, sparc64, strongarm (amv4l) and ppc (external untested contributed code). In general if the assembly code exists for a given arhitecture and the compiler knows inline assembly (for example sun cc does not) FAST_LOCK is prefered. The main advantage of using FAST_LOCK is very low memory overhead and extremely fast lock/unlock operations (like 20 times faster then SYSV semaphores on linux & 40 times on solaris). The only thing that comes close to them are pthread mutexes (which are about 3-4 times slower).
16
+ PTHREAD_MUTEX - uses pthread_mutex_lock/unlock. They are quite fast but they work between processes only on some systems (they do not work on linux).
17
+ POSIX_SEM  - uses posix semaphores (sem_wait/sem_post). They are slower then the previous methods but still way faster then SYSV sempahores. Unfortunately they also do not work  on all the systems (e.g. linux).
18
+ SYSV_SEM - this is the most portable but also the slowest locking method. Another problem is that the number of semaphores that can be alocated by a process is limited. One also has to free them before exiting.
19
+
20
+
21
+2. How to use it?
22
+-----------------
23
+
24
+First of all you have to include locking.h. Then when compiling the code one or all of FAST_LOCK, USE_PTHREAD_MUTEX, USE_PTHREAD_SEM or USE_SYSV_SEM must be defined (the ser Makefile.defs takes care of this, you should need to change it only for new arhitectures or compilers).
25
+
26
+locking.h defines 2 new types: gen_lock_t and lock_set_t.
27
+
28
+
29
+3. Simple locks
30
+---------------
31
+
32
+The simple locks are simple mutexes. The type is gen_lock_t.
33
+WARNING: do not make any assumptions on gen_lock_t base type, it does not have to be always an int.
34
+
35
+Allocation & initialization:
36
+----------------------------
37
+
38
+The locks are allocated with:
39
+   gen_lock_t* lock_alloc();
40
+and initialized with:
41
+   gen_lock_t* lock_init(gen_lock_t* lock);
42
+
43
+Both function return 0 on failure.
44
+The locks must be initialized before use.
45
+
46
+A proper alloc/init sequence looks like:
47
+
48
+gen_lock_t* lock;
49
+
50
+lock=lock_alloc();
51
+if (lock==0) goto error;
52
+if (lock_init(lock)==0){
53
+   lock_dealloc(lock);
54
+   goto error; /* could not init lock*/
55
+}
56
+...
57
+
58
+Lock allocation can be skipped in some cases: if the lock is already in shared memory you don't need to allocate it again, you can initialize it directly, but keep in mind that the lock MUST be in shared memory.
59
+
60
+Example:
61
+
62
+struct s {
63
+    int foo;
64
+    gen_lock_t lock;
65
+} bar;
66
+
67
+bar=shm_malloc(sizeof struct s); /* we allocate it in the shared memory */
68
+if (lock_init(&bar->lock)==0){
69
+ /* error initializing the lock */
70
+ ...
71
+}
72
+
73
+
74
+Destroying & deallocating the locks:
75
+------------------------------------
76
+
77
+  void    lock_destroy(gen_lock_t* lock);
78
+  void    lock_dealloc(gen_lock_t* lock);
79
+ 
80
+ The lock_destroy function must be called first. It removes the resources associated with the lock, but it does not also free the lock shared memory part. Think of sysv rmid.
81
+ Please don't forget to call this function, or you can leave allocated resources in some cases (e.g sysv semaphores). Be carefull to call it in your module destroy function if you use any global module locks.
82
+
83
+Example:
84
+lock_destroy(lock);
85
+lock_dealloc(lock);
86
+
87
+
88
+Of course you don't need to call lock_dealloc if your lock was not allocated with lock_alloc.
89
+
90
+
91
+Locking & unlocking:
92
+--------------------
93
+
94
+void    lock_get(gen_lock_t* lock);      - lock (mutex down)
95
+void    lock_release(gen_lock_t* lock);  - unlock (mutex up)
96
+
97
+
98
+
99
+4. Lock Sets
100
+------------
101
+
102
+The lock sets are kind of sysv semaphore sets equivalent. The type is lock_set_t.
103
+Use them when you need a lot of mutexes. In some cases they waste less system resources than arrays of gen_lock_t (e.g. sys v semaphores).
104
+
105
+Allocating & initializing:
106
+--------------------------
107
+
108
+lock_set_t* lock_set_alloc(int no);
109
+lock_set_t* lock_set_init(lock_set_t* set);
110
+
111
+Both functions return 0 on failure.
112
+
113
+WARNING: expect the allocation function to fail for large numbers. It depends on the locking method used & the system available resources (again the sysv semaphores example).
114
+
115
+Example:
116
+
117
+lock_set_t *lock_set;
118
+
119
+lock_set=lock_set_alloc(100);
120
+if (lock_set==0) goto error;
121
+if (lock_set_init(lock_set)==0){
122
+   lock_set_dealloc(lock_set);
123
+   goto error;
124
+}
125
+
126
+
127
+Destroying & deallocating:
128
+--------------------------
129
+  void lock_set_destroy(lock_set_t* s);
130
+  void lock_set_dealloc(lock_set_t* s);
131
+
132
+Again don't forget to "destroy" the locks.
133
+
134
+
135
+Locking & unlocking:
136
+--------------------
137
+
138
+void lock_set_get(lock_set_t* s, int i);
139
+void lock_set_release(lock_set_t* s, int i);
140
+
141
+Example:
142
+
143
+lock_set_get(lock_set, 2);
144
+/* do something */
145
+lock_set_release(lock_set, 2);
146
+
147
+