Browse code

Use INTPTR_MIN instead of INTPTR_MAX (because i find it prettier now). Improve documentation. Move to indirect URLs in .bootstrap.

Nat! authored on 23/10/2016 12:42:56
Showing 8 changed files
1 1
deleted file mode 100644
... ...
@@ -1 +0,0 @@
1
-https://github.com
... ...
@@ -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 92
 }
93 93
 ```
94 94
 
95
-`value` can be any `void *` except `NULL` or `(void *) INTPTR_MAX`.  It will
95
+`value` can be any `void *` except `NULL` or `(void *) INTPTR_MIN`.  It will
96 96
 not get dereferenced by the hashmap.
97 97
 
98 98
 
... ...
@@ -107,8 +105,8 @@ Return Values:
107 107
 
108 108
 ```
109 109
 int  mulle_concurrent_hashmap_remove( struct mulle_concurrent_hashmap *map,
110
-                                       intptr_t hash,
111
-                                       void *value)
110
+                                      intptr_t hash,
111
+                                      void *value)
112 112
 ```
113 113
 
114 114
 Remove a `hash`, `value` pair. Read the description of
... ...
@@ -135,6 +133,16 @@ Return Values:
135 135
 *   NULL  : not found
136 136
 *   otherwise the value for this hash
137 137
 
138
+
139
+### `mulle_concurrent_hashmap_enumerate`
140
+
141
+```
142
+struct mulle_concurrent_hashmapenumerator  mulle_concurrent_hashmap_enumerate( struct mulle_concurrent_hashmap *map)
143
+```
144
+
145
+Enumerate a hashtable. See `mulle_concurrent_hashmapenumerator_next` for more details.
146
+It returns a `mulle_concurrent_hashmapenumerator`. This enumerator should not be jointly accessed by multiple threads.
147
+
138 148
 ---
139 149
 
140 150
 
... ...
@@ -150,12 +158,21 @@ number maybe not as meaningful as one might think, if the map is accessed in mul
150 150
 
151 151
 # `mulle_concurrent_hashmapenumerator`
152 152
 
153
+The following two functions operate on an enumerator over the possibly multi-threaded hashmap, the enumerator itself should not be accessed by multiple threads.
154
+
155
+* `mulle_concurrent_hashmapenumerator_next`
156
+* `mulle_concurrent_hashmapenumerator_done`
157
+
158
+
159
+### `mulle_concurrent_hashmapenumerator_next`
160
+
153 161
 ```
154
-struct mulle_concurrent_hashmapenumerator  mulle_concurrent_hashmap_enumerate( struct mulle_concurrent_hashmap *map)
162
+int  mulle_concurrent_hashmapenumerator_next( struct mulle_concurrent_hashmapenumerator *rover,
163
+                                               intptr_t *hash,
164
+                                               void **value)
155 165
 ```
156 166
 
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
167
+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 168
 environments, the enumeration may be interrupted by mutations of the hashtable
160 169
 by other threads. The enumerator itself should not be shared with other threads.
161 170
 
... ...
@@ -177,20 +194,10 @@ retry:
177 177
    }
178 178
    mulle_concurrent_hashmapenumerator_done( &rover);
179 179
 
180
-   if( rval == EBUSY)
181
-      goto retry;  // restart from the beginning
180
+   if( rval == EBUSY) // interrupted!
181
+      goto retry;     // restart from the beginning will duplicate some
182 182
 ```
183 183
 
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 184
 Return Values:
195 185
 
196 186
 *   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 40
 
41 41
 Initialize `array`, with a starting `size` of elements. `allocator` will be
42 42
 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.
43
+for `allocator` to use the default. This needs to be called in **single-threaded** fashion.
44
+
45
+##### Return Values:
46
+
47
+*   0      : OK
48
+*   EINVAL : invalid argument
49
+*   ENOMEM : out of memory
44 50
 
45 51
 
46 52
 ### `mulle_concurrent_pointerarray_done`
... ...
@@ -50,11 +54,9 @@ void  mulle_concurrent_pointerarray_done( struct mulle_concurrent_pointerarray *
50 50
 ```
51 51
 
52 52
 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.
53
+itself though. `array` must be a valid pointer. This needs to be called in **single-threaded** fashion.
55 54
 
56 55
 
57
-## multi-threaded
58 56
 
59 57
 
60 58
 ### `mulle_concurrent_pointerarray_add`
... ...
@@ -65,11 +67,11 @@ int  mulle_concurrent_pointerarray_add( struct mulle_concurrent_pointerarray *ar
65 65
 ```
66 66
 
67 67
 Add value to the end of the array.
68
-`value` can be any `void *` except `NULL` or `(void *) INTPTR_MAX`. It will
68
+`value` can be any `void *` except `NULL` or `(void *) INTPTR_MIN`. It will
69 69
 not get dereferenced by the pointerarray.
70 70
 
71 71
 
72
-Return Values:
72
+##### Return Values:
73 73
 
74 74
 *   0      : OK
75 75
 *   EINVAL : invalid argument
... ...
@@ -85,7 +87,8 @@ void   *mulle_concurrent_pointerarray_get( struct mulle_concurrent_pointerarray
85 85
 
86 86
 Get value at `index` of array.
87 87
 
88
-Return Values:
88
+##### Return Values:
89
+
89 90
 *   NULL  : not found (invalid argument)
90 91
 *   otherwise the value
91 92
 
... ...
@@ -107,11 +110,18 @@ unsigned int   mulle_concurrent_pointerarray_get_count( struct mulle_concurrent_
107 107
 ```
108 108
 
109 109
 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.
110
+grow this value is useful, but possibly outdated.
111 111
 
112 112
 
113 113
 ## `mulle_concurrent_pointerarrayenumerator`
114 114
 
115
+
116
+The following operations should be executed by a single thread only, but the environment can be multi-threaded:
117
+
118
+* `mulle_concurrent_pointerarrayenumerator_next`
119
+* `mulle_concurrent_pointerarrayenumerator_done`
120
+
121
+
115 122
 ### `mulle_concurrent_pointerarray_enumerate`
116 123
 
117 124
 ```
... ...
@@ -146,7 +156,8 @@ void   *mulle_concurrent_pointerarrayenumerator_next( struct mulle_concurrent_po
146 146
 
147 147
 Get the next value from the enumerator.
148 148
 
149
-Return Values:
149
+##### Return Values:
150
+
150 151
 *   NULL  : nothing left
151 152
 *   otherwise the value
152 153
 
... ...
@@ -163,16 +174,21 @@ It may be left out.
163 163
 
164 164
 ## `mulle_concurrent_pointerarrayreverseenumerator`
165 165
 
166
+The following operations should be executed by a single thread only, but the environment can be multi-threaded:
167
+
168
+* `mulle_concurrent_pointerarrayreverseenumerator_next`
169
+* `mulle_concurrent_pointerarrayreverseenumerator_done`
170
+
166 171
 
167 172
 ### `mulle_concurrent_pointerarray_reverseenumerate`
168 173
 
169 174
 ```
170
-struct mulle_concurrent_pointerarrayreverseenumerator  mulle_concurrent_pointerarray_reverseenumerate( struct mulle_concurrent_pointerarray *array)
175
+struct mulle_concurrent_pointerarrayreverseenumerator  mulle_concurrent_pointerarray_reverseenumerate( struct mulle_concurrent_pointerarray *array, unsigned int n)
171 176
 ```
172 177
 
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.
178
+Reverse enumerate a pointerarray (n-1 to 0). You have to supply the `n`.
179
+This works reliably even in multi-threaded environments, but the enumerator
180
+itself should not be shared with other threads though.
176 181
 
177 182
 
178 183
 ### `mulle_concurrent_pointerarrayreverseenumerator_next`
... ...
@@ -183,7 +199,8 @@ void   *mulle_concurrent_pointerarrayreverseenumerator_next( struct mulle_concur
183 183
 
184 184
 Get the next value from the enumerator.
185 185
 
186
-Return Values:
186
+##### Return Values:
187
+
187 188
 *   NULL  : nothing left
188 189
 *   otherwise the value
189 190
 
... ...
@@ -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 */