Browse code

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

Andrei Pelinescu-Onciul authored on 12/03/2003 12:56:36
Showing 4 changed files
... ...
@@ -12,6 +12,8 @@
12 12
 #  2003-02-24  make install no longer overwrites ser.cfg  - patch provided
13 13
 #               by Maxim Sobolev   <sobomax@FreeBSD.org> and 
14 14
 #                  Tomas Bj´┐Żrklund <tomas@webservices.se>
15
+#  2003-03-11  PREFIX & LOCALBASE must also be exported (andrei)
16
+#
15 17
 
16 18
 auto_gen=lex.yy.c cfg.tab.c   #lexx, yacc etc
17 19
 
... ...
@@ -48,6 +50,7 @@ include Makefile.defs
48 48
 #export relevant variables to the sub-makes
49 49
 export DEFS PROFILE CC  LD MKDEP MKTAGS CFLAGS LDFLAGS MOD_CFLAGS MOD_LDFLAGS
50 50
 export LEX YACC YACC_FLAGS
51
+export PREFIX LOCALBASE
51 52
 
52 53
 
53 54
 # include the common rules
54 55
new file mode 100644
... ...
@@ -0,0 +1,147 @@
0
+# $Id$
1
+#
2
+# History:
3
+#---------
4
+#  2003-03-11  created by andrei
5
+
6
+
7
+SER locking interface
8
+
9
+
10
+1. Why use it?
11
+   ----------
12
+
13
+ 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:
14
+ 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).
15
+ 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).
16
+ 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).
17
+ 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.
18
+
19
+
20
+2. How to use it?
21
+-----------------
22
+
23
+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).
24
+
25
+locking.h defines 2 new types: gen_lock_t and lock_set_t.
26
+
27
+
28
+3. Simple locks
29
+---------------
30
+
31
+The simple locks are simple mutexes. The type is gen_lock_t.
32
+WARNING: do not make any assumptions on gen_lock_t base type, it does not have to be always an int.
33
+
34
+Allocation & initialization:
35
+----------------------------
36
+
37
+The locks are allocated with:
38
+   gen_lock_t* lock_alloc();
39
+and initialized with:
40
+   gen_lock_t* lock_init(gen_lock_t* lock);
41
+
42
+Both function return 0 on failure.
43
+The locks must be initialized before use.
44
+
45
+A proper alloc/init sequence looks like:
46
+
47
+gen_lock_t* lock;
48
+
49
+lock=lock_alloc();
50
+if (lock==0) goto error;
51
+if (lock_init(lock)==0){
52
+   lock_dealloc(lock);
53
+   goto error; /* could not init lock*/
54
+}
55
+...
56
+
57
+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.
58
+
59
+Example:
60
+
61
+struct s {
62
+    int foo;
63
+    gen_lock_t lock;
64
+} bar;
65
+
66
+bar=shm_malloc(sizeof struct s); /* we allocate it in the shared memory */
67
+if (lock_init(&bar->lock)==0){
68
+ /* error initializing the lock */
69
+ ...
70
+}
71
+
72
+
73
+Destroying & deallocating the locks:
74
+------------------------------------
75
+
76
+  void    lock_destroy(gen_lock_t* lock);
77
+  void    lock_dealloc(gen_lock_t* lock);
78
+ 
79
+ 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.
80
+ 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.
81
+
82
+Example:
83
+lock_destroy(lock);
84
+lock_dealloc(lock);
85
+
86
+
87
+Of course you don't need to call lock_dealloc if your lock was not allocated with lock_alloc.
88
+
89
+
90
+Locking & unlocking:
91
+--------------------
92
+
93
+void    lock_get(gen_lock_t* lock);      - lock (mutex down)
94
+void    lock_release(gen_lock_t* lock);  - unlock (mutex up)
95
+
96
+
97
+
98
+4. Lock Sets
99
+------------
100
+
101
+The lock sets are kind of sysv semaphore sets equivalent. The type is lock_set_t.
102
+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).
103
+
104
+Allocating & initializing:
105
+--------------------------
106
+
107
+lock_set_t* lock_set_alloc(int no);
108
+lock_set_t* lock_set_init(lock_set_t* set);
109
+
110
+Both functions return 0 on failure.
111
+
112
+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).
113
+
114
+Example:
115
+
116
+lock_set_t *lock_set;
117
+
118
+lock_set=lock_set_alloc(100);
119
+if (lock_set==0) goto error;
120
+if (lock_set_init(lock_set)==0){
121
+   lock_set_dealloc(lock_set);
122
+   goto error;
123
+}
124
+
125
+
126
+Destroying & deallocating:
127
+--------------------------
128
+  void lock_set_destroy(lock_set_t* s);
129
+  void lock_set_dealloc(lock_set_t* s);
130
+
131
+Again don't forget to "destroy" the locks.
132
+
133
+
134
+Locking & unlocking:
135
+--------------------
136
+
137
+void lock_set_get(lock_set_t* s, int i);
138
+void lock_set_release(lock_set_t* s, int i);
139
+
140
+Example:
141
+
142
+lock_set_get(lock_set, 2);
143
+/* do something */
144
+lock_set_release(lock_set, 2);
145
+
146
+
... ...
@@ -39,6 +39,7 @@ Implements (in lock_ops.h & lock_alloc.h):
39 39
 
40 40
 	simple locks:
41 41
 	-------------
42
+	type: gen_lock_t
42 43
 	gen_lock_t* lock_alloc();                - allocates a lock in shared mem.
43 44
 	gen_lock_t* lock_init(gen_lock_t* lock); - inits the lock
44 45
 	void    lock_destroy(gen_lock_t* lock);  - removes the lock (e.g sysv rmid)
... ...
@@ -46,8 +47,9 @@ Implements (in lock_ops.h & lock_alloc.h):
46 46
 	void    lock_get(gen_lock_t* lock);      - lock (mutex down)
47 47
 	void    lock_release(gen_lock_t* lock);  - unlock (mutex up)
48 48
 	
49
-	lock sets: [implemented only for FL & SYSV so far]
49
+	lock sets:
50 50
 	----------
51
+	type: lock_set_t
51 52
 	lock_set_t* lock_set_alloc(no)               - allocs a lock set in shm.
52 53
 	lock_set_t* lock_set_init(lock_set_t* set);  - inits the lock set
53 54
 	void lock_set_destroy(lock_set_t* s);        - removes the lock set
54 55
new file mode 100644
... ...
@@ -0,0 +1,60 @@
0
+
1
+
2
+1 linux-i386/gcc2.96
3
+2 linux-i386/gcc3.2
4
+3 linux-i386/icc
5
+4 freebsd-i386/gcc
6
+5 openbsd-i386/gcc
7
+6 netbsd-ultrasparc/gcc
8
+7 solaris/gcc
9
+8 solaris/sun cc
10
+
11
+W - warnings
12
+E - errors
13
+I - could not compile due to missing includes
14
+L - could not compile due to missing libraries
15
+l - locking problems
16
+o - ok
17
+
18
+P - possible proto problems (tcp)
19
+D - dead/not finished
20
+
21
+
22
+
23
+
24
+module_name       1  2  3  4  5  6  7  8
25
+core
26
+acc                                    o
27
+auth                                   E
28
+auth_db                                W
29
+auth_radius                            I
30
+cpl             P                      o
31
+cpl-c           D                      E
32
+dbtext                                 E
33
+domain                                 o
34
+enum                                   o
35
+exec                                   o
36
+ext                                    o
37
+extcmd                                 o
38
+group                                  o
39
+jabber                                 o
40
+maxfwd                                 o
41
+msilo                                  o
42
+mysql                                  o
43
+pa                                     o
44
+pike                                   o
45
+print                                  o
46
+radius_acc                             I
47
+registrar                              o
48
+rr                                     o
49
+sl                                     o
50
+sms                                    o
51
+textops                                o
52
+tm                                     o
53
+uri                                    o
54
+usrloc                                 E
55
+vm                                     o
56
+
57
+
58
+
59
+