51Degrees Device Detection C/C++
4.1Newer Version 4.4
Resources to be managed by a resource manager.
Resource : a pointer to anything which needs to be replaced or freed in a thread-safe manor
Manager : manages access to a resource by handing out handles and altering the resource safely
Handle : a reference to a resource which is being managed. This is the only way in which a resource should be accessed
A Resource is a structure which can be changed or freed at any time, so is managed by a resource manager to allow safe concurrent access. Any resource which is being used will not be changed or freed until the last reference to it has been released.
A resource manager is created by allocating the memory for the structure and calling the fiftyoneDegreesResourceManagerInit method to give it a resource to manage, and a method to free it when necessary.
A handle to a resource can be fetched from a resource manager using the fiftyoneDegreesResourceHandleIncUse method. This increments the "in use" counter in a thread safe manor and returns an exclusive handle to the resource.
When getting a handle to a resource, if all the available handles are in use then the method will block until one is available.
Once a resource handle is finished with, it must be released back to the resource manager using the fiftyoneDegreesResourceHandleDecUse method. This releases the handle so it is available to other threads.
A resource manager is freed, along with its resource, using the fiftyoneDegreesResourceManagerFree method. This prevents any new handles from being acquired, and frees the resource being managed. If the resource has active handles, then a free method does not block. Instead it prevents new handles from being acquired and sets the manager to free the resource once the last handle has been released.
A resource can be replaced using the fiftyoneDegreesResourceReplace method. This swaps the resource being managed so that any new requests for a handle return the new resource. The existing resource is freed once the last active handle to it has been released.
| union | fiftyoneDegreesResourceHandleCounter
Contains the number of active uses of the resource. More...
|
| struct | fiftyoneDegreesResourceHandle
Tracks the number of active uses of the resource within the manager. More...
|
| struct | fiftyoneDegreesResourceManager
Manager structure used to provide access to a shared and changing resource. More...
|
| void | fiftyoneDegreesResourceManagerInit (fiftyoneDegreesResourceManager *manager, void *resource, fiftyoneDegreesResourceHandle **resourceHandle, void(*freeResource)(void *))
Initialise a preallocated resource manager structure with a resource for it to manage access to. More...
|
| void | fiftyoneDegreesResourceManagerFree (fiftyoneDegreesResourceManager *manager)
Frees any data associated with the manager and releases the resource making it eligible for freeing. More...
|
| fiftyoneDegreesResourceHandle * | fiftyoneDegreesResourceHandleIncUse (fiftyoneDegreesResourceManager *manager)
Increments the usage counter for the resource and returns a handle that can be used to reference it. More...
|
| void | fiftyoneDegreesResourceHandleDecUse (fiftyoneDegreesResourceHandle *handle)
Decrements the usage counter. More...
|
| void | fiftyoneDegreesResourceReplace (fiftyoneDegreesResourceManager *manager, void *newResource, fiftyoneDegreesResourceHandle **newResourceHandle)
Replaces the resource with the new resource. More...
|
| void fiftyoneDegreesResourceHandleDecUse | ( | fiftyoneDegreesResourceHandle * | handle | ) |
Decrements the usage counter.
If the count reaches zero then resource will become eligible to be freed either when the manager replaces it or when the manager is freed.
| fiftyoneDegreesResourceHandle* fiftyoneDegreesResourceHandleIncUse | ( | fiftyoneDegreesResourceManager * | manager | ) |
Increments the usage counter for the resource and returns a handle that can be used to reference it.
The handle MUST be used to decrement the use count using the fiftyoneDegreesResourceHandleDecUse method when the resource is finished with. The resource can be guaranteed not to be freed until after the decrement method has been called.
| void fiftyoneDegreesResourceManagerFree | ( | fiftyoneDegreesResourceManager * | manager | ) |
Frees any data associated with the manager and releases the resource making it eligible for freeing.
IMPORTANT : The resource itself is not necessarily freed after this operation i.e. if there are still handles pointing to this resource, then the freeing will be left until the last handle is released. For this reason, the manager pointer MUST remain valid until the last handle has been released.
| void fiftyoneDegreesResourceManagerInit | ( | fiftyoneDegreesResourceManager * | manager, |
| void * | resource, | ||
| fiftyoneDegreesResourceHandle ** | resourceHandle, | ||
| void(*)(void *) | freeResource | ||
| ) |
Initialise a preallocated resource manager structure with a resource for it to manage access to.
The resourceHandle parameter must point to the handle within the resource under management so that the handle can be assigned to the resource before the resource is placed under management.
IMPORTANT : The pointer to the manager MUST remain valid for the duration of any resource's existence i.e. until the last handle has been released and the resource freed.
| void fiftyoneDegreesResourceReplace | ( | fiftyoneDegreesResourceManager * | manager, |
| void * | newResource, | ||
| fiftyoneDegreesResourceHandle ** | newResourceHandle | ||
| ) |
Replaces the resource with the new resource.
If the existing resource is not being used it will be freed. Otherwise it is left to the decrement function to free the resource when the usage count is zero.