Browse code

Use INTPTR_MIN instead of INTPTR_MAX (because i find it prettier now). Improve documentation.

Nat! authored on 23-10-2016 12:42:56
Showing 7 changed files
... ...
@@ -3,8 +3,7 @@
3 3
 #    echo "https://www.mulle-kybernetik.com/repositories" > .bootstrap.local/MULLE_REPOSITORIES
4 4
 #
5 5
 # override the branches like so:
6
-#    echo "master" > .bootstrap.local/MULLE_THREAD_BRANCH
6
+#    echo "master" > .bootstrap.local/MULLE_ABA_BRANCH
7 7
 
8
-${MULLE_REPOSITORIES}/mulle-thread;;${MULLE_THREAD_BRANCH:-release}
9
-${MULLE_REPOSITORIES}/mulle-allocator;;${MULLE_ALLOCATOR_BRANCH:-release}
8
+# aba pulls threads and allocators
10 9
 ${MULLE_REPOSITORIES}/mulle-aba;;${MULLE_ABA_BRANCH:-release}
... ...
@@ -1,4 +1,4 @@
1
-1.0.1-1.0.4
1
+1.0.1-1.0.5
2 2
 ===
3 3
 
4 4
 * fix packaging
... ...
@@ -25,8 +25,6 @@ The following operations work in multi-threaded environments, but should be
25 25
 approached with caution:
26 26
 
27 27
 * `mulle_concurrent_hashmap_enumerate`
28
-* `mulle_concurrent_hashmapenumerator_next`
29
-* `mulle_concurrent_hashmapenumerator_done`
30 28
 * `mulle_concurrent_hashmap_lookup_any`
31 29
 * `mulle_concurrent_hashmap_count`
32 30
 * `mulle_concurrent_hashmap_get_size`
... ...
@@ -92,7 +90,7 @@ static inline uint64_t   mulle_hash_avalanche64(uint64_t h)
92 90
 }
93 91
 ```
94 92
 
95
-`value` can be any `void *` except `NULL` or `(void *) INTPTR_MAX`.  It will
93
+`value` can be any `void *` except `NULL` or `(void *) INTPTR_MIN`.  It will
96 94
 not get dereferenced by the hashmap.
97 95
 
98 96
 
... ...
@@ -107,8 +105,8 @@ Return Values:
107 105
 
108 106
 ```
109 107
 int  mulle_concurrent_hashmap_remove( struct mulle_concurrent_hashmap *map,
110
-                                       intptr_t hash,
111
-                                       void *value)
108
+                                      intptr_t hash,
109
+                                      void *value)
112 110
 ```
113 111
 
114 112
 Remove a `hash`, `value` pair. Read the description of
... ...
@@ -135,6 +133,16 @@ Return Values:
135 133
 *   NULL  : not found
136 134
 *   otherwise the value for this hash
137 135
 
136
+
137
+### `mulle_concurrent_hashmap_enumerate`
138
+
139
+```
140
+struct mulle_concurrent_hashmapenumerator  mulle_concurrent_hashmap_enumerate( struct mulle_concurrent_hashmap *map)
141
+```
142
+
143
+Enumerate a hashtable. See `mulle_concurrent_hashmapenumerator_next` for more details.
144
+It returns a `mulle_concurrent_hashmapenumerator`. This enumerator should not be jointly accessed by multiple threads.
145
+
138 146
 ---
139 147
 
140 148
 
... ...
@@ -150,12 +158,21 @@ number maybe not as meaningful as one might think, if the map is accessed in mul
150 158
 
151 159
 # `mulle_concurrent_hashmapenumerator`
152 160
 
161
+The following two functions operate on an enumerator over the possibly multi-threaded hashmap, the enumerator itself should not be accessed by multiple threads.
162
+
163
+* `mulle_concurrent_hashmapenumerator_next`
164
+* `mulle_concurrent_hashmapenumerator_done`
165
+
166
+
167
+### `mulle_concurrent_hashmapenumerator_next`
168
+
153 169
 ```
154
-struct mulle_concurrent_hashmapenumerator  mulle_concurrent_hashmap_enumerate( struct mulle_concurrent_hashmap *map)
170
+int  mulle_concurrent_hashmapenumerator_next( struct mulle_concurrent_hashmapenumerator *rover,
171
+                                               intptr_t *hash,
172
+                                               void **value)
155 173
 ```
156 174
 
157
-Enumerate a hashtable. This works reliably if `map` is accessed in
158
-single-threaded fashion, which it probably will NOT be. In multi-threaded
175
+Get the next `hash`, `value` pair from the enumerator. This works reliably if `map` is accessed in single-threaded fashion, which it probably will NOT be. In multi-threaded
159 176
 environments, the enumeration may be interrupted by mutations of the hashtable
160 177
 by other threads. The enumerator itself should not be shared with other threads.
161 178
 
... ...
@@ -177,20 +194,10 @@ retry:
177 194
    }
178 195
    mulle_concurrent_hashmapenumerator_done( &rover);
179 196
 
180
-   if( rval == EBUSY)
181
-      goto retry;  // restart from the beginning
197
+   if( rval == EBUSY) // interrupted!
198
+      goto retry;     // restart from the beginning will duplicate some
182 199
 ```
183 200
 
184
-### `mulle_concurrent_hashmapenumerator_next`
185
-
186
-```
187
-int  mulle_concurrent_hashmapenumerator_next( struct mulle_concurrent_hashmapenumerator *rover,
188
-                                               intptr_t *hash,
189
-                                               void **value)
190
-```
191
-
192
-Get the next `hash`, `value` pair from the enumerator.
193
-
194 201
 Return Values:
195 202
 
196 203
 *   1          : OK
... ...
@@ -16,18 +16,16 @@ The following operations are fine in multi-threaded environments:
16 16
 * `mulle_concurrent_pointerarray_add`
17 17
 * `mulle_concurrent_pointerarray_get`
18 18
 * `mulle_concurrent_pointerarray_enumerate`
19
-* `mulle_concurrent_pointerarrayenumerator_next`
20
-* `mulle_concurrent_pointerarrayenumerator_done`
21 19
 * `mulle_concurrent_pointerarray_reverseenumerate`
22
-* `mulle_concurrent_pointerarrayreverseenumerator_next`
23
-* `mulle_concurrent_pointerarrayreverseenumerator_done`
24 20
 * `mulle_concurrent_pointerarray_map`
25 21
 * `mulle_concurrent_pointerarray_find`
26 22
 * `mulle_concurrent_pointerarray_get_count`
27 23
 * `mulle_concurrent_pointerarray_get_size`
28 24
 
29 25
 
30
-## single-threaded
26
+
27
+
28
+
31 29
 
32 30
 
33 31
 ### `mulle_concurrent_pointerarray_init`
... ...
@@ -40,7 +38,13 @@ int   mulle_concurrent_pointerarray_init( struct mulle_concurrent_pointerarray *
40 38
 
41 39
 Initialize `array`, with a starting `size` of elements. `allocator` will be
42 40
 used to allocate and free memory during the lifetime of `array`.  You can pass in
43
-for `allocator` to use the default. Call this in single-threaded fashion.
41
+for `allocator` to use the default. This needs to be called in **single-threaded** fashion.
42
+
43
+##### Return Values:
44
+
45
+*   0      : OK
46
+*   EINVAL : invalid argument
47
+*   ENOMEM : out of memory
44 48
 
45 49
 
46 50
 ### `mulle_concurrent_pointerarray_done`
... ...
@@ -50,11 +54,9 @@ void  mulle_concurrent_pointerarray_done( struct mulle_concurrent_pointerarray *
50 54
 ```
51 55
 
52 56
 This will free all allocated resources `array`. It will not **free** `array`
53
-itself though. `array` must be a valid pointer. Call this in single-threaded
54
-fashion.
57
+itself though. `array` must be a valid pointer. This needs to be called in **single-threaded** fashion.
55 58
 
56 59
 
57
-## multi-threaded
58 60
 
59 61
 
60 62
 ### `mulle_concurrent_pointerarray_add`
... ...
@@ -65,11 +67,11 @@ int  mulle_concurrent_pointerarray_add( struct mulle_concurrent_pointerarray *ar
65 67
 ```
66 68
 
67 69
 Add value to the end of the array.
68
-`value` can be any `void *` except `NULL` or `(void *) INTPTR_MAX`. It will
70
+`value` can be any `void *` except `NULL` or `(void *) INTPTR_MIN`. It will
69 71
 not get dereferenced by the pointerarray.
70 72
 
71 73
 
72
-Return Values:
74
+##### Return Values:
73 75
 
74 76
 *   0      : OK
75 77
 *   EINVAL : invalid argument
... ...
@@ -85,7 +87,8 @@ void   *mulle_concurrent_pointerarray_get( struct mulle_concurrent_pointerarray
85 87
 
86 88
 Get value at `index` of array.
87 89
 
88
-Return Values:
90
+##### Return Values:
91
+
89 92
 *   NULL  : not found (invalid argument)
90 93
 *   otherwise the value
91 94
 
... ...
@@ -107,11 +110,18 @@ unsigned int   mulle_concurrent_pointerarray_get_count( struct mulle_concurrent_
107 110
 ```
108 111
 
109 112
 This gives you the current number of entries in `array`. As the array can only
110
-grow this value is useful, but maybe already outdated.
113
+grow this value is useful, but possibly outdated.
111 114
 
112 115
 
113 116
 ## `mulle_concurrent_pointerarrayenumerator`
114 117
 
118
+
119
+The following operations should be executed by a single thread only, but the environment can be multi-threaded:
120
+
121
+* `mulle_concurrent_pointerarrayenumerator_next`
122
+* `mulle_concurrent_pointerarrayenumerator_done`
123
+
124
+
115 125
 ### `mulle_concurrent_pointerarray_enumerate`
116 126
 
117 127
 ```
... ...
@@ -146,7 +156,8 @@ void   *mulle_concurrent_pointerarrayenumerator_next( struct mulle_concurrent_po
146 156
 
147 157
 Get the next value from the enumerator.
148 158
 
149
-Return Values:
159
+##### Return Values:
160
+
150 161
 *   NULL  : nothing left
151 162
 *   otherwise the value
152 163
 
... ...
@@ -163,16 +174,21 @@ It may be left out.
163 174
 
164 175
 ## `mulle_concurrent_pointerarrayreverseenumerator`
165 176
 
177
+The following operations should be executed by a single thread only, but the environment can be multi-threaded:
178
+
179
+* `mulle_concurrent_pointerarrayreverseenumerator_next`
180
+* `mulle_concurrent_pointerarrayreverseenumerator_done`
181
+
166 182
 
167 183
 ### `mulle_concurrent_pointerarray_reverseenumerate`
168 184
 
169 185
 ```
170
-struct mulle_concurrent_pointerarrayreverseenumerator  mulle_concurrent_pointerarray_reverseenumerate( struct mulle_concurrent_pointerarray *array)
186
+struct mulle_concurrent_pointerarrayreverseenumerator  mulle_concurrent_pointerarray_reverseenumerate( struct mulle_concurrent_pointerarray *array, unsigned int n)
171 187
 ```
172 188
 
173
-Reverse enumerate a pointerarray (n-1 to 0). This works reliably even
174
-in multi-threaded environments. The enumerator itself should not be shared
175
-with other threads though.
189
+Reverse enumerate a pointerarray (n-1 to 0). You have to supply the `n`.
190
+This works reliably even in multi-threaded environments, but the enumerator
191
+itself should not be shared with other threads though.
176 192
 
177 193
 
178 194
 ### `mulle_concurrent_pointerarrayreverseenumerator_next`
... ...
@@ -183,7 +199,8 @@ void   *mulle_concurrent_pointerarrayreverseenumerator_next( struct mulle_concur
183 199
 
184 200
 Get the next value from the enumerator.
185 201
 
186
-Return Values:
202
+##### Return Values:
203
+
187 204
 *   NULL  : nothing left
188 205
 *   otherwise the value
189 206
 
... ...
@@ -111,7 +111,7 @@ static inline unsigned int  mulle_concurrent_hashmap_get_size( struct mulle_conc
111 111
 //   ENOMEM : must be out of memory
112 112
 //
113 113
 // Do not use hash=0
114
-// Do not use value=0 or value=INTPTR_MAX
114
+// Do not use value=0 or value=INTPTR_MIN
115 115
 //
116 116
 int   mulle_concurrent_hashmap_insert( struct mulle_concurrent_hashmap *map,
117 117
                                        intptr_t hash,
... ...
@@ -35,7 +35,7 @@
35 35
 #define mulle_concurrent_h__
36 36
 
37 37
 
38
-#define MULLE_CONCURRENT_VERSION  ((1 << 20) | (0 << 8) | 4)
38
+#define MULLE_CONCURRENT_VERSION  ((1 << 20) | (0 << 8) | 5)
39 39
 
40 40
 #include <mulle_thread/mulle_thread.h>
41 41
 #include <mulle_allocator/mulle_allocator.h>
... ...
@@ -44,7 +44,7 @@
44 44
 //
45 45
 #define MULLE_CONCURRENT_NO_HASH           0
46 46
 
47
-#define MULLE_CONCURRENT_INVALID_POINTER   ((void *) INTPTR_MAX)
47
+#define MULLE_CONCURRENT_INVALID_POINTER   ((void *) INTPTR_MIN)
48 48
 #define MULLE_CONCURRENT_NO_POINTER        ((void *) 0)
49 49
 
50 50
 #endif /* mulle_concurrent_types_h */