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_G   (&raphf_globals)
#define	PHP_RAPHF_DEBUG_PHANDLES   0

Enumerations
enum	ZEND_RESULT_CODE { SUCCESS = 0, FAILURE = -1 }

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

Enumeration Type Documentation

enum ZEND_RESULT_CODE

Enumerator
SUCCESS
FAILURE

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	(	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_persistent_handle_resource_factory_init(NULL, pf);
    } 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	(	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

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),
     "1.1.0" ,
    ZEND_MODULE_GLOBALS(raphf),
    PHP_GINIT(raphf),
    PHP_GSHUTDOWN(raphf),
    NULL,
    STANDARD_MODULE_PROPERTIES_EX
}