Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.
Concurrency and allocation
By default the allocator classes do no locking. However, some allocators have a member struct of type whalloc_mutex which defines three properties:
- int (*lock)( void * )
- int (*unlock)( void * )
- void * state
If lock() is set then it is called whenever the internals need to lock the allocator object (during de/allocation), passing allocator->mutex.state as its only argument. The locker should acquire its lock (which is presumably referenced via the state member). Likewise, the unlock() function is passed the state pointer and should unlock the mutex. They should return 0 on success. Allocator API routines which respect the mutex will fail if locking fails.
Under no circumstances it it safe to alter the state of an allocator object, except for the few obligatory exceptions:
- The client must set up the mutex member before concurrent access to the object becomes possible.
- For certain allocator classes (e.g. whalloc_bt) the client may set the allocator's 'log' or 'fallback` members, as long as he locks/unlocks the allocator (if needed) before doing so, or does so before concurrent access becomes possible (e.g. by locking the mutex before doing initialization of the object). Changing the 'fallback' member later is illegal, but the logger can be switched out at any time (set to NULL to disable it).
Once set, the mutex members should never be re-assigned. Doing so might lead to undefined behaviour, in particular if it is done while a recursive lock is held.
All other state of an allocator can be read from, but do not do so without locking the (if the app needs it). Also do not depend on the structure of a given allocator class - it is subject to change, and it only in the public API so that we can stack-allocate the allocators. Under no circumstances, except those few mentioned above, should a client change any allocator state. That is the private domain of the internal allocator APIs.
The library defines a shared object named whalloc_mutex_trace which can be copied to get locking routines which do no locking, but instead send a notification to stderr.