51Degrees Device Detection C/C++  4.1

A device detection library that is used natively or by 51Degrees products

Resource Manager

Detailed Description

Resources to be managed by a resource manager.

Terms

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

Introduction

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.

Create

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.

Get

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.

Release

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.

Free

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.

Replace

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.

Usage Example

typedef struct someResourceType {
fiftyoneDegreesResourceHandle *handle;
void *data;
}
someResourceType *resource;
fiftyoneDegreesResourceManager manager;
// Initialise the resource manager with a resource
fiftyoneDegreesResourceManagerInit(
&manager,
resource,
&resource->handle,
Free);
// Check that the resource handle was set successfully
if (resource->handle != NULL) {
// Get a handle to the resource to ensure it is not freed by any
// other threads
someResourceType *localResource = (someResourceType*)
fiftyoneDegreesResourceHandleIncUse(&manager)->resource;
// Free the resource. This operation will be postponed until there are
// no remaining handled being used
fiftyoneDegreesResourceManagerFree(&manager);
// Do something with the resource while it is guaranteed to be available
// ...
// Release the resource so other threads know it is eligible for freeing
fiftyoneDegreesResourceHandleDecUse(resource->handle);
// This is the point where the call to free the manager will actually
// be carried out now that nothing is referencing the resource
}

Collaboration diagram for Resource Manager:

Structs

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...

Functions

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...

Function Documentation

◆ fiftyoneDegreesResourceHandleDecUse()

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.

Parameters
handle - to the resource which should be released by the manager

◆ fiftyoneDegreesResourceHandleIncUse()

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.

Parameters
manager - the resource manager to initialise with the resource

◆ fiftyoneDegreesResourceManagerFree()

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.

Parameters
manager - the resource manager to initialise with the resource
Examples
Hash/GettingStarted.c, Hash/MatchMetrics.c, Hash/OfflineProcessing.c, and Hash/StronglyTyped.c.

◆ fiftyoneDegreesResourceManagerInit()

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.

Parameters
manager - the resource manager to initialise with the resource
resource - pointer to the resource which the manager should manage access to
resourceHandle - points to the location the new handle should be stored
freeResource - method to use when freeing the resource

◆ fiftyoneDegreesResourceReplace()

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.

Parameters
manager - the resource manager to initialise with the resource
newResource - pointer to the resource which the manager should manage access to
newResourceHandle - points to the location the new handle should be stored
On This Page

Generated by doxygen 1.8.15