Documentation: assoc_array: Indent function explanation text

+84 -83

1 changed file

expand all

Documentation

core-api

+84 -83

Documentation/core-api/assoc_array.rst

··· 92 92 93 93 void assoc_array_apply_edit(struct assoc_array_edit *edit); 94 94 95 - This will perform the edit functions, interpolating various write barriers 96 - to permit accesses under the RCU read lock to continue. The edit script 97 - will then be passed to ``call_rcu()`` to free it and any dead stuff it points 98 - to. 95 + This will perform the edit functions, interpolating various write barriers 96 + to permit accesses under the RCU read lock to continue. The edit script 97 + will then be passed to ``call_rcu()`` to free it and any dead stuff it 98 + points to. 99 99 100 100 2. Cancel an edit script:: 101 101 102 102 void assoc_array_cancel_edit(struct assoc_array_edit *edit); 103 103 104 - This frees the edit script and all preallocated memory immediately. If 105 - this was for insertion, the new object is _not_ released by this function, 106 - but must rather be released by the caller. 104 + This frees the edit script and all preallocated memory immediately. If 105 + this was for insertion, the new object is *not* released by this function, 106 + but must rather be released by the caller. 107 107 108 108 These functions are guaranteed not to fail. 109 109 ··· 123 123 124 124 unsigned long (*get_key_chunk)(const void *index_key, int level); 125 125 126 - This should return a chunk of caller-supplied index key starting at the 127 - *bit* position given by the level argument. The level argument will be a 128 - multiple of ``ASSOC_ARRAY_KEY_CHUNK_SIZE`` and the function should return 129 - ``ASSOC_ARRAY_KEY_CHUNK_SIZE bits``. No error is possible. 126 + This should return a chunk of caller-supplied index key starting at the 127 + *bit* position given by the level argument. The level argument will be a 128 + multiple of ``ASSOC_ARRAY_KEY_CHUNK_SIZE`` and the function should return 129 + ``ASSOC_ARRAY_KEY_CHUNK_SIZE bits``. No error is possible. 130 130 131 131 132 132 2. Get a chunk of an object's index key:: 133 133 134 134 unsigned long (*get_object_key_chunk)(const void *object, int level); 135 135 136 - As the previous function, but gets its data from an object in the array 137 - rather than from a caller-supplied index key. 136 + As the previous function, but gets its data from an object in the array 137 + rather than from a caller-supplied index key. 138 138 139 139 140 140 3. See if this is the object we're looking for:: 141 141 142 142 bool (*compare_object)(const void *object, const void *index_key); 143 143 144 - Compare the object against an index key and return ``true`` if it matches and 145 - ``false`` if it doesn't. 144 + Compare the object against an index key and return ``true`` if it matches 145 + and ``false`` if it doesn't. 146 146 147 147 148 148 4. Diff the index keys of two objects:: 149 149 150 150 int (*diff_objects)(const void *object, const void *index_key); 151 151 152 - Return the bit position at which the index key of the specified object 153 - differs from the given index key or -1 if they are the same. 152 + Return the bit position at which the index key of the specified object 153 + differs from the given index key or -1 if they are the same. 154 154 155 155 156 156 5. Free an object:: 157 157 158 158 void (*free_object)(void *object); 159 159 160 - Free the specified object. Note that this may be called an RCU grace period 161 - after ``assoc_array_apply_edit()`` was called, so ``synchronize_rcu()`` may be 162 - necessary on module unloading. 160 + Free the specified object. Note that this may be called an RCU grace period 161 + after ``assoc_array_apply_edit()`` was called, so ``synchronize_rcu()`` may 162 + be necessary on module unloading. 163 163 164 164 165 165 Manipulation Functions ··· 171 171 172 172 void assoc_array_init(struct assoc_array *array); 173 173 174 - This initialises the base structure for an associative array. It can't fail. 174 + This initialises the base structure for an associative array. It can't fail. 175 175 176 176 177 177 2. Insert/replace an object in an associative array:: ··· 182 182 const void *index_key, 183 183 void *object); 184 184 185 - This inserts the given object into the array. Note that the least 186 - significant bit of the pointer must be zero as it's used to type-mark 187 - pointers internally. 185 + This inserts the given object into the array. Note that the least 186 + significant bit of the pointer must be zero as it's used to type-mark 187 + pointers internally. 188 188 189 - If an object already exists for that key then it will be replaced with the 190 - new object and the old one will be freed automatically. 189 + If an object already exists for that key then it will be replaced with the 190 + new object and the old one will be freed automatically. 191 191 192 - The ``index_key`` argument should hold index key information and is 193 - passed to the methods in the ops table when they are called. 192 + The ``index_key`` argument should hold index key information and is 193 + passed to the methods in the ops table when they are called. 194 194 195 - This function makes no alteration to the array itself, but rather returns 196 - an edit script that must be applied. ``-ENOMEM`` is returned in the case of 197 - an out-of-memory error. 195 + This function makes no alteration to the array itself, but rather returns 196 + an edit script that must be applied. ``-ENOMEM`` is returned in the case of 197 + an out-of-memory error. 198 198 199 - The caller should lock exclusively against other modifiers of the array. 199 + The caller should lock exclusively against other modifiers of the array. 200 200 201 201 202 202 3. Delete an object from an associative array:: ··· 206 206 const struct assoc_array_ops *ops, 207 207 const void *index_key); 208 208 209 - This deletes an object that matches the specified data from the array. 209 + This deletes an object that matches the specified data from the array. 210 210 211 - The ``index_key`` argument should hold index key information and is 212 - passed to the methods in the ops table when they are called. 211 + The ``index_key`` argument should hold index key information and is 212 + passed to the methods in the ops table when they are called. 213 213 214 - This function makes no alteration to the array itself, but rather returns 215 - an edit script that must be applied. ``-ENOMEM`` is returned in the case of 216 - an out-of-memory error. ``NULL`` will be returned if the specified object is 217 - not found within the array. 214 + This function makes no alteration to the array itself, but rather returns 215 + an edit script that must be applied. ``-ENOMEM`` is returned in the case of 216 + an out-of-memory error. ``NULL`` will be returned if the specified object 217 + is not found within the array. 218 218 219 219 The caller should lock exclusively against other modifiers of the array. 220 220 ··· 225 225 assoc_array_clear(struct assoc_array *array, 226 226 const struct assoc_array_ops *ops); 227 227 228 - This deletes all the objects from an associative array and leaves it 229 - completely empty. 228 + This deletes all the objects from an associative array and leaves it 229 + completely empty. 230 230 231 - This function makes no alteration to the array itself, but rather returns 232 - an edit script that must be applied. ``-ENOMEM`` is returned in the case of 233 - an out-of-memory error. 231 + This function makes no alteration to the array itself, but rather returns 232 + an edit script that must be applied. ``-ENOMEM`` is returned in the case of 233 + an out-of-memory error. 234 234 235 - The caller should lock exclusively against other modifiers of the array. 235 + The caller should lock exclusively against other modifiers of the array. 236 236 237 237 238 238 5. Destroy an associative array, deleting all objects:: ··· 240 240 void assoc_array_destroy(struct assoc_array *array, 241 241 const struct assoc_array_ops *ops); 242 242 243 - This destroys the contents of the associative array and leaves it 244 - completely empty. It is not permitted for another thread to be traversing 245 - the array under the RCU read lock at the same time as this function is 246 - destroying it as no RCU deferral is performed on memory release - 247 - something that would require memory to be allocated. 243 + This destroys the contents of the associative array and leaves it 244 + completely empty. It is not permitted for another thread to be traversing 245 + the array under the RCU read lock at the same time as this function is 246 + destroying it as no RCU deferral is performed on memory release - 247 + something that would require memory to be allocated. 248 248 249 - The caller should lock exclusively against other modifiers and accessors 250 - of the array. 249 + The caller should lock exclusively against other modifiers and accessors 250 + of the array. 251 251 252 252 253 253 6. Garbage collect an associative array:: ··· 257 257 bool (*iterator)(void *object, void *iterator_data), 258 258 void *iterator_data); 259 259 260 - This iterates over the objects in an associative array and passes each one to 261 - ``iterator()``. If ``iterator()`` returns ``true``, the object is kept. If it 262 - returns ``false``, the object will be freed. If the ``iterator()`` function 263 - returns ``true``, it must perform any appropriate refcount incrementing on the 264 - object before returning. 260 + This iterates over the objects in an associative array and passes each one 261 + to ``iterator()``. If ``iterator()`` returns ``true``, the object is kept. 262 + If it returns ``false``, the object will be freed. If the ``iterator()`` 263 + function returns ``true``, it must perform any appropriate refcount 264 + incrementing on the object before returning. 265 265 266 - The internal tree will be packed down if possible as part of the iteration 267 - to reduce the number of nodes in it. 266 + The internal tree will be packed down if possible as part of the iteration 267 + to reduce the number of nodes in it. 268 268 269 - The ``iterator_data`` is passed directly to ``iterator()`` and is otherwise 270 - ignored by the function. 269 + The ``iterator_data`` is passed directly to ``iterator()`` and is otherwise 270 + ignored by the function. 271 271 272 - The function will return ``0`` if successful and ``-ENOMEM`` if there wasn't 273 - enough memory. 272 + The function will return ``0`` if successful and ``-ENOMEM`` if there wasn't 273 + enough memory. 274 274 275 - It is possible for other threads to iterate over or search the array under 276 - the RCU read lock while this function is in progress. The caller should 277 - lock exclusively against other modifiers of the array. 275 + It is possible for other threads to iterate over or search the array under 276 + the RCU read lock while this function is in progress. The caller should 277 + lock exclusively against other modifiers of the array. 278 278 279 279 280 280 Access Functions ··· 289 289 void *iterator_data), 290 290 void *iterator_data); 291 291 292 - This passes each object in the array to the iterator callback function. 293 - ``iterator_data`` is private data for that function. 292 + This passes each object in the array to the iterator callback function. 293 + ``iterator_data`` is private data for that function. 294 294 295 - This may be used on an array at the same time as the array is being 296 - modified, provided the RCU read lock is held. Under such circumstances, 297 - it is possible for the iteration function to see some objects twice. If 298 - this is a problem, then modification should be locked against. The 299 - iteration algorithm should not, however, miss any objects. 295 + This may be used on an array at the same time as the array is being 296 + modified, provided the RCU read lock is held. Under such circumstances, 297 + it is possible for the iteration function to see some objects twice. If 298 + this is a problem, then modification should be locked against. The 299 + iteration algorithm should not, however, miss any objects. 300 300 301 - The function will return ``0`` if no objects were in the array or else it will 302 - return the result of the last iterator function called. Iteration stops 303 - immediately if any call to the iteration function results in a non-zero 304 - return. 301 + The function will return ``0`` if no objects were in the array or else it 302 + will return the result of the last iterator function called. Iteration 303 + stops immediately if any call to the iteration function results in a 304 + non-zero return. 305 305 306 306 307 307 2. Find an object in an associative array:: ··· 310 310 const struct assoc_array_ops *ops, 311 311 const void *index_key); 312 312 313 - This walks through the array's internal tree directly to the object 314 - specified by the index key.. 313 + This walks through the array's internal tree directly to the object 314 + specified by the index key. 315 315 316 - This may be used on an array at the same time as the array is being 317 - modified, provided the RCU read lock is held. 316 + This may be used on an array at the same time as the array is being 317 + modified, provided the RCU read lock is held. 318 318 319 - The function will return the object if found (and set ``*_type`` to the object 320 - type) or will return ``NULL`` if the object was not found. 319 + The function will return the object if found (and set ``*_type`` to the 320 + object 321 + type) or will return ``NULL`` if the object was not found. 321 322 322 323 323 324 Index Key Form

Configure Feed

Configure Feed