php_raphf_api.c File Reference

#include "php.h"
#include "php_ini.h"
#include "ext/standard/info.h"
#include "php_raphf.h"

Include dependency graph for php_raphf_api.c:

Macros
#define	PHP_RAPHF_TEST   0
#define	PHP_RAPHF_G   (&raphf_globals)
#define	PHP_RAPHF_DEBUG_PHANDLES   0

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...
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...
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_accrete (php_persistent_handle_factory_t *a, void *handle)
	Copy 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_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...
php_resource_factory_ops_t *	php_persistent_handle_get_resource_factory_ops (void)
	Retrieve persistent handle resource factory ops. More...
	ZEND_END_ARG_INFO ()
	STD_PHP_INI_ENTRY ("raphf.persistent_handle.limit","-1", PHP_INI_SYSTEM, OnUpdateLong, persistent_handle.limit, zend_raphf_globals, raphf_globals) static HashTable *php_persistent_handles_global_hash
	PHP_MINIT_FUNCTION (raphf)
	PHP_MSHUTDOWN_FUNCTION (raphf)
	PHP_MINFO_FUNCTION (raphf)

Variables
struct php_persistent_handle_globals	persistent_handle
zend_module_entry	raphf_module_entry

Macro Definition Documentation

#define PHP_RAPHF_DEBUG_PHANDLES   0

#define PHP_RAPHF_G   (&raphf_globals)

Referenced by PHP_MINFO_FUNCTION(), PHP_MINIT_FUNCTION(), php_persistent_handle_cleanup(), php_persistent_handle_concede(), php_persistent_handle_provide(), php_persistent_handle_release(), and php_persistent_handle_statall().

#define PHP_RAPHF_TEST   0

Function Documentation

PHP_MINFO_FUNCTION

(

raphf

)

PHP_MINIT_FUNCTION

(

raphf

)

PHP_MSHUTDOWN_FUNCTION

(

raphf

)

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:

STD_PHP_INI_ENTRY	(	"raphf.persistent_handle.limit"	,
		"-1"	,
		PHP_INI_SYSTEM	,
		OnUpdateLong	,
		persistent_handle.	limit,
		zend_raphf_globals	,
		raphf_globals
	)

ZEND_END_ARG_INFO

(

)

Variable Documentation

struct php_persistent_handle_globals persistent_handle

zend_module_entry raphf_module_entry

Initial value:

= {
    STANDARD_MODULE_HEADER,
    "raphf",
    raphf_functions,
    PHP_MINIT(raphf),
    PHP_MSHUTDOWN(raphf),
    NULL,
    NULL,
    PHP_MINFO(raphf),
     "2.0.0dev" ,
    ZEND_MODULE_GLOBALS(raphf),
    PHP_GINIT(raphf),
    PHP_GSHUTDOWN(raphf),
    NULL,
    STANDARD_MODULE_PROPERTIES_EX
}