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:

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:

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

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

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

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

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

Parameters

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

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

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

a	the persistent handle factory
handle	the 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

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

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

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

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

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

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