![]() |
Resource and persistent handle factory API
A facility to manage possibly persistent resources with a comprehensible API. Provides simliar functionality like the zend_list API, but with more flexiblity and freedom.
|
Go to the source code of this file.
Data Structures | |
struct | php_resource_factory_ops |
The resource ops consisting of a ctor, a copy ctor and a dtor. More... | |
struct | php_resource_factory |
The resource factory. More... | |
struct | php_persistent_handle_list |
Persistent handles storage. More... | |
struct | php_persistent_handle_provider |
Definition of a persistent handle provider. More... | |
struct | php_persistent_handle_factory |
Definition of a persistent handle factory. More... | |
struct | php_persistent_handle_factory.ident |
The ident for which this factory manages resources. More... | |
Typedefs | |
typedef void *(* | php_resource_factory_handle_ctor_t) (void *opaque, void *init_arg) |
A resource constructor. More... | |
typedef void *(* | php_resource_factory_handle_copy_t) (void *opaque, void *handle) |
The copy constructor of a resource. More... | |
typedef void(* | php_resource_factory_handle_dtor_t) (void *opaque, void *handle) |
The destructor of a resource. More... | |
typedef struct php_resource_factory_ops | php_resource_factory_ops_t |
The resource ops consisting of a ctor, a copy ctor and a dtor. More... | |
typedef struct php_resource_factory | php_resource_factory_t |
The resource factory. More... | |
typedef struct php_persistent_handle_list | php_persistent_handle_list_t |
Persistent handles storage. More... | |
typedef struct php_persistent_handle_provider | php_persistent_handle_provider_t |
Definition of a persistent handle provider. More... | |
typedef struct php_persistent_handle_factory | php_persistent_handle_factory_t |
typedef void(* | php_persistent_handle_wakeup_t) (php_persistent_handle_factory_t *f, void **handle) |
Wakeup the persistent handle on re-acquisition. More... | |
typedef void(* | php_persistent_handle_retire_t) (php_persistent_handle_factory_t *f, void **handle) |
Retire the persistent handle on release. More... | |
Functions | |
php_resource_factory_t * | php_resource_factory_init (php_resource_factory_t *f, php_resource_factory_ops_t *fops, void *data, void(*dtor)(void *data)) |
Initialize a resource factory. More... | |
unsigned | php_resource_factory_addref (php_resource_factory_t *rf) |
Increase the refcount of the resource factory. More... | |
void | php_resource_factory_dtor (php_resource_factory_t *f) |
Destroy the resource factory. More... | |
void | php_resource_factory_free (php_resource_factory_t **f) |
Destroy and free the resource factory. More... | |
void * | php_resource_factory_handle_ctor (php_resource_factory_t *f, void *init_arg) |
Construct a resource by the resource factory f. More... | |
void * | php_resource_factory_handle_copy (php_resource_factory_t *f, void *handle) |
Create a copy of the resource handle. More... | |
void | php_resource_factory_handle_dtor (php_resource_factory_t *f, void *handle) |
Destroy (and free) the resource. More... | |
int | php_persistent_handle_provide (const char *name_str, size_t name_len, php_resource_factory_ops_t *fops, void *data, void(*dtor)(void *)) |
Register a persistent handle provider in MINIT. More... | |
php_persistent_handle_factory_t * | php_persistent_handle_concede (php_persistent_handle_factory_t *a, const char *name_str, size_t name_len, const char *ident_str, size_t ident_len, php_persistent_handle_wakeup_t wakeup, php_persistent_handle_retire_t retire) |
Retrieve a persistent handle factory at runtime. More... | |
void | php_persistent_handle_abandon (php_persistent_handle_factory_t *a) |
Abandon the persistent handle factory. More... | |
void * | php_persistent_handle_acquire (php_persistent_handle_factory_t *a, void *init_arg) |
Acquire a persistent handle. More... | |
void | php_persistent_handle_release (php_persistent_handle_factory_t *a, void *handle) |
Release a persistent handle. More... | |
void * | php_persistent_handle_accrete (php_persistent_handle_factory_t *a, void *handle) |
Copy a persistent handle. More... | |
php_resource_factory_ops_t * | php_persistent_handle_get_resource_factory_ops (void) |
Retrieve persistent handle resource factory ops. More... | |
php_resource_factory_t * | php_persistent_handle_resource_factory_init (php_resource_factory_t *a, php_persistent_handle_factory_t *pf) |
Create a resource factory for persistent handles. More... | |
zend_bool | php_resource_factory_is_persistent (php_resource_factory_t *a) |
Check whether a resource factory is a persistent handle resource factory. More... | |
void | php_persistent_handle_cleanup (const char *name_str, size_t name_len, const char *ident_str, size_t ident_len) |
Clean persistent handles up. More... | |
HashTable * | php_persistent_handle_statall (HashTable *ht) |
Retrieve statistics about the current process/thread's persistent handles. More... | |
struct php_resource_factory_ops |
The resource ops consisting of a ctor, a copy ctor and a dtor.
Define this ops and register them with php_persistent_handle_provide() in MINIT.
Data Fields | ||
---|---|---|
php_resource_factory_handle_copy_t | copy | The resource's copy constructor. |
php_resource_factory_handle_ctor_t | ctor | The resource constructor. |
php_resource_factory_handle_dtor_t | dtor | The resource's destructor. |
struct php_persistent_handle_list |
struct php_persistent_handle_provider |
Definition of a persistent handle provider.
Holds a resource factory an a persistent handle list.
Data Fields | ||
---|---|---|
php_persistent_handle_list_t | list |
The list of free handles. Hash of "ident" => array(handles) entries. Persistent handles are acquired out of this list. |
php_resource_factory_t | rf |
The resource factory. New handles are created by this factory. |
struct php_persistent_handle_factory |
Definition of a persistent handle factory.
php_persistent_handle_concede() will return a pointer to a php_persistent_handle_factory if a provider for the name_str has been registered with php_persistent_handle_provide().
Data Fields | ||
---|---|---|
unsigned | free_on_abandon:1 | Whether it has to be free'd on php_persistent_handle_abandon() |
struct php_persistent_handle_factory | ident | The ident for which this factory manages resources. |
php_persistent_handle_provider_t * | provider | The persistent handle provider. |
php_persistent_handle_retire_t | retire | The persistent handle retire routine; may be NULL. |
php_persistent_handle_wakeup_t | wakeup | The persistent handle wakeup routine; may be NULL. |
struct php_persistent_handle_factory.ident |
typedef struct php_persistent_handle_factory php_persistent_handle_factory_t |
typedef struct php_persistent_handle_list php_persistent_handle_list_t |
Persistent handles storage.
typedef struct php_persistent_handle_provider php_persistent_handle_provider_t |
Definition of a persistent handle provider.
Holds a resource factory an a persistent handle list.
typedef void(* php_persistent_handle_retire_t) (php_persistent_handle_factory_t *f, void **handle) |
Retire the persistent handle on release.
typedef void(* php_persistent_handle_wakeup_t) (php_persistent_handle_factory_t *f, void **handle) |
Wakeup the persistent handle on re-acquisition.
typedef void*(* php_resource_factory_handle_copy_t) (void *opaque, void *handle) |
The copy constructor of a resource.
opaque | the factory's data |
handle | the (persistent) handle to copy |
typedef void*(* php_resource_factory_handle_ctor_t) (void *opaque, void *init_arg) |
A resource constructor.
opaque | is the data from php_persistent_handle_provide() |
init_arg | is the init_arg from php_resource_factory_init() |
typedef void(* php_resource_factory_handle_dtor_t) (void *opaque, void *handle) |
The destructor of a resource.
opaque | the factory's data |
handle | the handle to destroy |
typedef struct php_resource_factory_ops php_resource_factory_ops_t |
The resource ops consisting of a ctor, a copy ctor and a dtor.
Define this ops and register them with php_persistent_handle_provide() in MINIT.
typedef struct php_resource_factory php_resource_factory_t |
The resource factory.
void php_persistent_handle_abandon | ( | php_persistent_handle_factory_t * | a | ) |
Abandon the persistent handle factory.
Destroy a php_persistent_handle_factory created by php_persistent_handle_concede(). If the memory for the factory was allocated, it will automatically be free'd.
a | the persistent handle factory to destroy |
Referenced by php_persistent_handle_resource_factory_init(), and php_resource_factory_is_persistent().
void* php_persistent_handle_accrete | ( | php_persistent_handle_factory_t * | a, |
void * | handle | ||
) |
Copy a persistent handle.
Let the underlying resource factory copy the handle.
a | the persistent handle factory |
handle | the resource to accrete |
void* php_persistent_handle_acquire | ( | php_persistent_handle_factory_t * | a, |
void * | init_arg | ||
) |
Acquire a persistent handle.
That is, either re-use a resource from the free list or create a new handle.
If a handle is acquired from the free list, the php_persistent_handle_factory::wakeup callback will be executed for that handle.
a | the persistent handle factory |
init_arg | the init_arg for php_resource_factory_handle_ctor() |
void php_persistent_handle_cleanup | ( | const char * | name_str, |
size_t | name_len, | ||
const char * | ident_str, | ||
size_t | ident_len | ||
) |
Clean persistent handles up.
Destroy persistent handles of provider name_str and in subsidiary namespace ident_str.
If name_str is NULL, all persistent handles of all providers with a matching ident_str will be cleaned up.
If ident_str is NULL all persistent handles of the provider will be cleaned up.
Ergo, if both, name_str and ident_str are NULL, then all persistent handles will be cleaned up.
You must call this in MSHUTDOWN, if your resource factory ops hold a registered php_resource_factory::dtor, else the dtor will point to memory not any more available if the extension has already been unloaded.
name_str | the provider name; may be NULL |
name_len | the provider name length |
ident_str | the subsidiary namespace name; may be NULL |
ident_len | the subsidiary namespace name length |
php_persistent_handle_factory_t* php_persistent_handle_concede | ( | php_persistent_handle_factory_t * | a, |
const char * | name_str, | ||
size_t | name_len, | ||
const char * | ident_str, | ||
size_t | ident_len, | ||
php_persistent_handle_wakeup_t | wakeup, | ||
php_persistent_handle_retire_t | retire | ||
) |
Retrieve a persistent handle factory at runtime.
If a persistent handle provider has been registered for name_str, a new php_persistent_handle_factory creating resources in the ident_str namespace will be constructed.
The wakeup routine wakeup and the retire routine retire will be assigned to the new php_persistent_handle_factory.
a | pointer to a factory; allocated on the heap if NULL |
name_str | the provider name, e.g. "http\Client\Curl" |
name_len | the provider name length, e.g. strlen("http\Client\Curl") |
ident_str | the subsidiary namespace, e.g. "php.net:80" |
ident_len | the subsidiary namespace lenght, e.g. strlen("php.net:80") |
wakeup | any persistent handle wakeup routine |
retire | any persistent handle retire routine |
php_resource_factory_ops_t* php_persistent_handle_get_resource_factory_ops | ( | void | ) |
Retrieve persistent handle resource factory ops.
These ops can be used to mask a persistent handle factory as resource factory itself, so you can transparently use the resource factory API, both for persistent and non-persistent ressources.
Example:
Referenced by php_persistent_handle_resource_factory_init().
int php_persistent_handle_provide | ( | const char * | name_str, |
size_t | name_len, | ||
php_resource_factory_ops_t * | fops, | ||
void * | data, | ||
void(*)(void *) | dtor | ||
) |
Register a persistent handle provider in MINIT.
Registers a factory provider for name_str with fops resource factory ops. Call this in your MINIT.
A php_resource_factory will be created with fops, data and dtor and will be stored together with a php_persistent_handle_list in the global raphf hash.
A php_persistent_handle_factory can then be retrieved by php_persistent_handle_concede() at runtime.
name_str | the provider name, e.g. "http\Client\Curl" |
name_len | the provider name length, e.g. strlen("http\Client\Curl") |
fops | the resource factory ops |
data | opaque user data |
dtor | data destructor |
void php_persistent_handle_release | ( | php_persistent_handle_factory_t * | a, |
void * | handle | ||
) |
Release a persistent handle.
That is, either put it back into the free list for later re-use or clean it up with php_resource_factory_handle_dtor().
If a handle is put back into the free list, the php_persistent_handle_factory::retire callback will be executed for that handle.
a | the persistent handle factory |
handle | the handle to release |
php_resource_factory_t* php_persistent_handle_resource_factory_init | ( | php_resource_factory_t * | a, |
php_persistent_handle_factory_t * | pf | ||
) |
Create a resource factory for persistent handles.
This will create a resource factory with persistent handle ops, which wraps the provided reource factory pf.
a | the persistent handle resource factory to initialize |
pf | the resource factory to wrap |
HashTable* php_persistent_handle_statall | ( | HashTable * | ht | ) |
unsigned php_resource_factory_addref | ( | php_resource_factory_t * | rf | ) |
Increase the refcount of the resource factory.
rf | the resource factory |
void php_resource_factory_dtor | ( | php_resource_factory_t * | f | ) |
Destroy the resource factory.
If the factory's refcount reaches 0, the dtor for data is called.
f | the resource factory |
Referenced by php_persistent_handle_provide(), and php_resource_factory_free().
void php_resource_factory_free | ( | php_resource_factory_t ** | f | ) |
Destroy and free the resource factory.
Calls php_resource_factory_dtor() and frees \æ f if the factory's refcount reached 0.
f | the resource factory |
void* php_resource_factory_handle_copy | ( | php_resource_factory_t * | f, |
void * | handle | ||
) |
Create a copy of the resource handle.
f | the resource factory |
handle | the resource to copy |
Referenced by php_persistent_handle_accrete().
void* php_resource_factory_handle_ctor | ( | php_resource_factory_t * | f, |
void * | init_arg | ||
) |
Construct a resource by the resource factory f.
f | the resource factory |
init_arg | for the resource constructor |
Referenced by php_persistent_handle_acquire().
void php_resource_factory_handle_dtor | ( | php_resource_factory_t * | f, |
void * | handle | ||
) |
Destroy (and free) the resource.
f | the resource factory |
handle | the resource to destroy |
Referenced by php_persistent_handle_release().
php_resource_factory_t* php_resource_factory_init | ( | php_resource_factory_t * | f, |
php_resource_factory_ops_t * | fops, | ||
void * | data, | ||
void(*)(void *data) | dtor | ||
) |
Initialize a resource factory.
If you register a dtor for a resource factory used with a persistent handle provider, be sure to call php_persistent_handle_cleanup() for your registered provider in MSHUTDOWN, else the dtor will point to no longer available memory if the extension has already been unloaded.
f | the factory to initialize; if NULL allocated on the heap |
fops | the resource ops to assign to the factory |
data | opaque user data; may be NULL |
dtor | a destructor for the data; may be NULL |
Referenced by php_persistent_handle_provide(), and php_persistent_handle_resource_factory_init().
zend_bool php_resource_factory_is_persistent | ( | php_resource_factory_t * | a | ) |
Check whether a resource factory is a persistent handle resource factory.
a | the resource factory to check |