php_raphf_api.h File Reference

#include "php_raphf.h"

Include dependency graph for php_raphf_api.h:

This graph shows which files directly or indirectly include this file:

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

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...
ZEND_RESULT_CODE	php_persistent_handle_provide (zend_string *name, 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, zend_string *name, zend_string *ident, 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 (zend_string *name, zend_string *ident)
	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:

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 has been registered with php_persistent_handle_provide().

Collaboration diagram for php_persistent_handle_factory:

Data Fields
unsigned	free_on_abandon:1	Whether it has to be free'd on php_persistent_handle_abandon()
zend_string *	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.

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

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.

Parameters

opaque	is the data from php_persistent_handle_provide()
init_arg	is 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

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.

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

a	the persistent handle factory to destroy

Referenced by php_persistent_handle_resource_factory_init(), and php_resource_factory_is_persistent().

Here is the caller graph for this function:

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

a	the persistent handle factory
handle	the resource to accrete

Here is the call graph for this function:

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

a	the persistent handle factory
init_arg	the init_arg for php_resource_factory_handle_ctor()

Returns

the acquired resource

Here is the call graph for this function:

void php_persistent_handle_cleanup	(	zend_string *	name,
		zend_string *	ident
	)

Clean persistent handles up.

Destroy persistent handles of provider name and in subsidiary namespace ident.

If name is NULL, all persistent handles of all providers with a matching ident will be cleaned up.

If identr is NULL all persistent handles of the provider will be cleaned up.

Ergo, if both, name and ident 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	the provider name; may be NULL
ident	the subsidiary namespace name; may be NULL

php_persistent_handle_factory_t* php_persistent_handle_concede	(	php_persistent_handle_factory_t *	a,
		zend_string *	name,
		zend_string *	ident,
		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, a new php_persistent_handle_factory creating resources in the ident namespace will be constructed.

The wakeup routine wakeup and the retire routine retire will be assigned to the new php_persistent_handle_factory.

Parameters

a	pointer to a factory; allocated on the heap if NULL
name	the provider name, e.g. "http\Client\Curl"
ident	the subsidiary namespace, e.g. "php.net:80"
wakeup	any persistent handle wakeup routine
retire	any 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(zend_string *persistent_id)
{
    php_resource_factory_t *rf;

    if (persistent_id) {
        php_persistent_handle_factory_t *pf;
        php_resource_factory_ops_t *ops;
        zend_string *ns = zend_string_init("my", 2, 1);

        ops = php_persistent_handle_get_resource_factory_ops();
        pf = php_persistent_handle_concede(NULL, ns, persistent_id, NULL, NULL);
        rf = php_persistent_handle_resource_factory_init(NULL, pf);
        zend_string_release(ns);
    } else {
        rf = php_resource_factory_init(NULL, &myops, NULL, NULL);
    }
    return rf;
}

Referenced by php_persistent_handle_resource_factory_init().

Here is the caller graph for this function:

ZEND_RESULT_CODE php_persistent_handle_provide	(	zend_string *	name,
		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	the provider name, e.g. "http\Client\Curl"
fops	the resource factory ops
data	opaque user data
dtor	data destructor

Returns

SUCCESS/FAILURE

Here is the call graph for this function:

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

a	the persistent handle factory
handle	the handle to release

Here is the call graph for this function:

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.

Parameters

a	the persistent handle resource factory to initialize
pf	the resource factory to wrap

Here is the call graph for this function:

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

rf	the 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

f	the resource factory

Referenced by php_persistent_handle_provide(), and php_resource_factory_free().

Here is the caller graph for this function:

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

f	the resource factory

Here is the call graph for this function:

void* php_resource_factory_handle_copy	(	php_resource_factory_t *	f,
		void *	handle
	)

Create a copy of the resource handle.

Parameters

f	the resource factory
handle	the resource to copy

Returns

the copy

Referenced by php_persistent_handle_accrete().

Here is the caller graph for this function:

void* php_resource_factory_handle_ctor	(	php_resource_factory_t *	f,
		void *	init_arg
	)

Construct a resource by the resource factory f.

Parameters

f	the resource factory
init_arg	for the resource constructor

Returns

the new resource

Referenced by php_persistent_handle_acquire().

Here is the caller graph for this function:

void php_resource_factory_handle_dtor	(	php_resource_factory_t *	f,
		void *	handle
	)

Destroy (and free) the resource.

Parameters

f	the resource factory
handle	the resource to destroy

Referenced by php_persistent_handle_release().

Here is the caller graph for this function:

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

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

Returns

f or an allocated resource factory

Referenced by php_persistent_handle_provide(), and php_persistent_handle_resource_factory_init().

Here is the caller graph for this function:

zend_bool php_resource_factory_is_persistent

(

php_resource_factory_t *

a

)

Check whether a resource factory is a persistent handle resource factory.

Parameters

a	the resource factory to check

Here is the call graph for this function: