Browse code

doc: Fix typos

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