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

Enumeration Type Documentation

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
athe 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
athe persistent handle factory
handlethe 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
athe persistent handle factory
init_argthe 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_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)
{
if (persistent_id_str) {
pf = php_persistent_handle_concede(NULL, "my", 2,
persistent_id_str, persistent_id_len, NULL, NULL TSRMLS_CC);
} 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_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

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
athe persistent handle factory
handlethe 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
athe persistent handle resource factory to initialize
pfthe 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:
1 [
2  "name" => [
3  "ident" => [
4  "used" => 1,
5  "free" => 0,
6  ]
7  ]
8 ]
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

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
fthe 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
fthe resource factory
handlethe 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
fthe resource factory
init_argfor 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
fthe resource factory
handlethe 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
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

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
athe 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
}