X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=html%2Fphp__raphf_8h.html;fp=html%2Fphp__raphf_8h.html;h=82818d0dfff33ad6c99d52f0c560cadf871e09ec;hb=31eab30b1296b8035c247dc4819dcb6da41bd838;hp=0000000000000000000000000000000000000000;hpb=c35c0bddcfac6e5bcd41949d401cc4d7cd98b4e3;p=m6w6%2Fext-raphf diff --git a/html/php__raphf_8h.html b/html/php__raphf_8h.html new file mode 100644 index 0000000..82818d0 --- /dev/null +++ b/html/php__raphf_8h.html @@ -0,0 +1,1207 @@ + + + + + + +Resource and persistent handle factory API: php_raphf.h File Reference + + + + + + + + + + + + + +
+
+ + + + + + + +
+
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.
+
+
+ + + + + +
+
+ +
+
+
+ +
+ +
+ All Data Structures Files Functions Variables Typedefs
+ + +
+ +
+ +
+
+Data Structures | +Typedefs | +Functions
+
+
php_raphf.h File Reference
+
+
+ +

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

Data Structure Documentation

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

Persistent handles storage.

+
+ + + + + + + +
Data Fields
+HashTable +free +Storage of free resources.
+ulong +used +Count of acquired resources.
+ +
+
+ +
+
+ + + + +
struct php_persistent_handle_provider
+
+

Definition of a persistent handle provider.

+

Holds a resource factory an a persistent handle list.

+
+Collaboration diagram for php_persistent_handle_provider:
+
+
Collaboration graph
+ + +
[legend]
+ + + + + + + + +
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().

+
+Collaboration diagram for php_persistent_handle_factory:
+
+
Collaboration graph
+ + +
[legend]
+ + + + + + + + + + + + + + + + + +
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
+
+

The ident for which this factory manages resources.

+
+ + + + + + + +
Data Fields
+size_t +len +ident length
+char * +str +ident string
+ +
+
+

Typedef Documentation

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

+
Parameters
+ + + +
opaquethe factory's data
handlethe (persistent) handle to copy
+
+
+ +
+
+ +
+
+ + + + +
typedef void*(* php_resource_factory_handle_ctor_t)(void *opaque, void *init_arg)
+
+ +

A resource constructor.

+
Parameters
+ + + +
opaqueis the data from php_persistent_handle_provide()
init_argis the init_arg from php_resource_factory_init()
+
+
+
Returns
the created (persistent) handle
+ +
+
+ +
+
+ + + + +
typedef void(* php_resource_factory_handle_dtor_t)(void *opaque, void *handle)
+
+ +

The destructor of a resource.

+
Parameters
+ + + +
opaquethe factory's data
handlethe 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.

+ +
+
+

Function Documentation

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

+
Parameters
+ + +
athe persistent handle factory to destroy
+
+
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + +
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.

+
Parameters
+ + + +
athe persistent handle factory
handlethe 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.

+
Parameters
+ + + +
athe persistent handle factory
init_argthe init_arg for php_resource_factory_handle_ctor()
+
+
+
Returns
the acquired resource
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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.

+
Parameters
+ + + + + +
name_strthe provider name; may be NULL
name_lenthe provider name length
ident_strthe subsidiary namespace name; may be NULL
ident_lenthe 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.

+
Parameters
+ + + + + + + + +
apointer to a factory; allocated on the heap if NULL
name_strthe provider name, e.g. "http\Client\Curl"
name_lenthe provider name length, e.g. strlen("http\Client\Curl")
ident_strthe subsidiary namespace, e.g. "php.net:80"
ident_lenthe subsidiary namespace lenght, e.g. strlen("php.net:80")
wakeupany persistent handle wakeup routine
retireany persistent handle retire routine
+
+
+
Returns
a or an allocated persistent handle factory
+ +
+
+ +
+
+ + + + + + + + +
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:

+
php_resource_factory_t *create_my_rf(const char *persistent_id_str,
+
size_t persistent_id_len TSRMLS_DC)
+
{
+
php_resource_factory_t *rf;
+
+
if (persistent_id_str) {
+
php_persistent_handle_factory_t *pf;
+
php_resource_factory_ops_t *ops;
+
+
ops = php_persistent_handle_get_resource_factory_ops();
+
+
pf = php_persistent_handle_concede(NULL, "my", 2,
+
persistent_id_str, persistent_id_len, NULL, NULL TSRMLS_CC);
+
+
rf = php_resource_factory_init(NULL, ops, pf, php_persistent_handle_abandon);
+
} else {
+
rf = php_resource_factory_init(NULL, &myops, NULL, NULL);
+
}
+
return rf;
+
}
+
+
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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.

+
Parameters
+ + + + + + +
name_strthe provider name, e.g. "http\Client\Curl"
name_lenthe provider name length, e.g. strlen("http\Client\Curl")
fopsthe resource factory ops
dataopaque user data
dtordata destructor
+
+
+
Returns
SUCCESS/FAILURE
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + +
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.

+
Parameters
+ + + +
athe persistent handle factory
handlethe handle to release
+
+
+ +
+
+ +
+
+ + + + + + + + +
HashTable* php_persistent_handle_statall (HashTable * ht)
+
+ +

Retrieve statistics about the current process/thread's persistent handles.

+
Returns
a HashTable like:
[
+
"name" => [
+
"ident" => [
+
"used" => 1,
+
"free" => 0,
+
]
+
]
+
]
+
+ +
+
+ +
+
+ + + + + + + + +
unsigned php_resource_factory_addref (php_resource_factory_t * rf)
+
+ +

Increase the refcount of the resource factory.

+
Parameters
+ + +
rfthe resource factory
+
+
+
Returns
the new refcount
+ +
+
+ +
+
+ + + + + + + + +
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.

+
Parameters
+ + +
fthe resource factory
+
+
+ +
+
+ +
+
+ + + + + + + + +
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.

+
Parameters
+ + +
fthe resource factory
+
+
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + +
void* php_resource_factory_handle_copy (php_resource_factory_t * f,
void * handle 
)
+
+ +

Create a copy of the resource handle.

+
Parameters
+ + + +
fthe resource factory
handlethe resource to copy
+
+
+
Returns
the copy
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + +
void* php_resource_factory_handle_ctor (php_resource_factory_t * f,
void * init_arg 
)
+
+ +

Construct a resource by the resource factory f.

+
Parameters
+ + + +
fthe resource factory
init_argfor the resource constructor
+
+
+
Returns
the new resource
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + +
void php_resource_factory_handle_dtor (php_resource_factory_t * f,
void * handle 
)
+
+ +

Destroy (and free) the resource.

+
Parameters
+ + + +
fthe resource factory
handlethe resource to destroy
+
+
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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.

+
Parameters
+ + + + + +
fthe factory to initialize; if NULL allocated on the heap
fopsthe resource ops to assign to the factory
dataopaque user data; may be NULL
dtora destructor for the data; may be NULL
+
+
+
Returns
f or an allocated resource factory
+ +
+
+
+
+ + + +