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.h
Go to the documentation of this file.
1 /*
2  +--------------------------------------------------------------------+
3  | PECL :: raphf |
4  +--------------------------------------------------------------------+
5  | Redistribution and use in source and binary forms, with or without |
6  | modification, are permitted provided that the conditions mentioned |
7  | in the accompanying LICENSE file are met. |
8  +--------------------------------------------------------------------+
9  | Copyright (c) 2013, Michael Wallner <mike@php.net> |
10  +--------------------------------------------------------------------+
11 */
12 
13 #ifndef PHP_RAPHF_API_H
14 #define PHP_RAPHF_API_H
15 
23 typedef void *(*php_resource_factory_handle_ctor_t)(void *opaque,
24  void *init_arg TSRMLS_DC);
25 
32 typedef void *(*php_resource_factory_handle_copy_t)(void *opaque,
33  void *handle TSRMLS_DC);
34 
41 typedef void (*php_resource_factory_handle_dtor_t)(void *opaque,
42  void *handle TSRMLS_DC);
43 
50 typedef struct php_resource_factory_ops {
58 
62 typedef struct php_resource_factory {
66  void *data;
68  void (*dtor)(void *data);
70  unsigned refcount;
72 
89  void (*dtor)(void *data));
90 
98 
107 
117 
126  void *init_arg TSRMLS_DC);
127 
136  void *handle TSRMLS_DC);
137 
145  void *handle TSRMLS_DC);
146 
152  HashTable free;
154  ulong used;
156 
168 
175 
177 
182  php_persistent_handle_factory_t *f, void **handle TSRMLS_DC);
187  php_persistent_handle_factory_t *f, void **handle TSRMLS_DC);
188 
203 
205  struct {
207  char *str;
209  size_t len;
210  } ident;
211 
213  unsigned free_on_abandon:1;
214 };
215 
236 PHP_RAPHF_API int /* SUCCESS|FAILURE */ php_persistent_handle_provide(
237  const char *name_str, size_t name_len, php_resource_factory_ops_t *fops,
238  void *data, void (*dtor)(void *) TSRMLS_DC);
239 
260  php_persistent_handle_factory_t *a, const char *name_str,
261  size_t name_len, const char *ident_str, size_t ident_len,
263  php_persistent_handle_retire_t retire TSRMLS_DC);
264 
276 
291  php_persistent_handle_factory_t *a, void *init_arg TSRMLS_DC);
292 
307  php_persistent_handle_factory_t *a, void *handle TSRMLS_DC);
308 
318  php_persistent_handle_factory_t *a, void *handle TSRMLS_DC);
319 
354 
367 
375 
400 PHP_RAPHF_API void php_persistent_handle_cleanup(const char *name_str,
401  size_t name_len, const char *ident_str, size_t ident_len TSRMLS_DC);
402 
418 PHP_RAPHF_API HashTable *php_persistent_handle_statall(HashTable *ht TSRMLS_DC);
419 
420 #endif /* PHP_RAPHF_API_H */
421 
422 
423 /*
424  * Local variables:
425  * tab-width: 4
426  * c-basic-offset: 4
427  * End:
428  * vim600: noet sw=4 ts=4 fdm=marker
429  * vim<600: noet sw=4 ts=4
430  */
void(* dtor)(void *data)
User data destructor.
Definition: php_raphf_api.h:68
void * data
Opaque user data.
Definition: php_raphf_api.h:66
php_resource_factory_handle_copy_t copy
The resource's copy constructor.
Definition: php_raphf_api.h:54
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.
Definition: php_raphf_api.c:350
void php_resource_factory_free(php_resource_factory_t **f)
Destroy and free the resource factory.
Definition: php_raphf_api.c:91
void *(* php_resource_factory_handle_ctor_t)(void *opaque, void *init_arg)
A resource constructor.
Definition: php_raphf_api.h:23
void(* php_persistent_handle_wakeup_t)(php_persistent_handle_factory_t *f, void **handle)
Wakeup the persistent handle on re-acquisition.
Definition: php_raphf_api.h:181
php_persistent_handle_list_t list
The list of free handles.
Definition: php_raphf_api.h:167
HashTable * php_persistent_handle_statall(HashTable *ht)
Retrieve statistics about the current process/thread's persistent handles.
Definition: php_raphf_api.c:526
unsigned php_resource_factory_addref(php_resource_factory_t *rf)
Increase the refcount of the resource factory.
Definition: php_raphf_api.c:75
void(* php_persistent_handle_retire_t)(php_persistent_handle_factory_t *f, void **handle)
Retire the persistent handle on release.
Definition: php_raphf_api.h:186
Persistent handles storage.
Definition: php_raphf_api.h:150
struct php_persistent_handle_list php_persistent_handle_list_t
Persistent handles storage.
unsigned refcount
How often this factory is referenced.
Definition: php_raphf_api.h:70
php_resource_factory_handle_dtor_t dtor
The resource's destructor.
Definition: php_raphf_api.h:56
void php_persistent_handle_abandon(php_persistent_handle_factory_t *a)
Abandon the persistent handle factory.
Definition: php_raphf_api.c:392
Definition of a persistent handle factory.
Definition: php_raphf_api.h:196
struct php_persistent_handle_factory::@0 ident
The ident for which this factory manages resources.
php_persistent_handle_retire_t retire
The persistent handle retire routine; may be NULL.
Definition: php_raphf_api.h:202
unsigned free_on_abandon
Whether it has to be free'd on php_persistent_handle_abandon()
Definition: php_raphf_api.h:213
php_resource_factory_t rf
The resource factory.
Definition: php_raphf_api.h:173
void *(* php_resource_factory_handle_copy_t)(void *opaque, void *handle)
The copy constructor of a resource.
Definition: php_raphf_api.h:32
#define PHP_RAPHF_API
Definition: php_raphf.h:26
void * php_persistent_handle_acquire(php_persistent_handle_factory_t *a, void *init_arg)
Acquire a persistent handle.
Definition: php_raphf_api.c:408
php_resource_factory_handle_ctor_t ctor
The resource constructor.
Definition: php_raphf_api.h:52
void(* php_resource_factory_handle_dtor_t)(void *opaque, void *handle)
The destructor of a resource.
Definition: php_raphf_api.h:41
HashTable free
Storage of free resources.
Definition: php_raphf_api.h:152
The resource ops consisting of a ctor, a copy ctor and a dtor.
Definition: php_raphf_api.h:50
php_persistent_handle_provider_t * provider
The persistent handle provider.
Definition: php_raphf_api.h:198
ulong used
Count of acquired resources.
Definition: php_raphf_api.h:154
php_resource_factory_ops_t * php_persistent_handle_get_resource_factory_ops(void)
Retrieve persistent handle resource factory ops.
Definition: php_raphf_api.c:549
void php_resource_factory_dtor(php_resource_factory_t *f)
Destroy the resource factory.
Definition: php_raphf_api.c:80
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.
Definition: php_raphf_api.c:128
struct php_resource_factory php_resource_factory_t
The resource factory.
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.
Definition: php_raphf_api.c:325
void * php_resource_factory_handle_ctor(php_resource_factory_t *f, void *init_arg)
Construct a resource by the resource factory f.
Definition: php_raphf_api.c:102
Definition of a persistent handle provider.
Definition: php_raphf_api.h:161
The resource factory.
Definition: php_raphf_api.h:62
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.
Definition: php_raphf_api.c:492
void php_persistent_handle_release(php_persistent_handle_factory_t *a, void *handle)
Release a persistent handle.
Definition: php_raphf_api.c:465
void php_resource_factory_handle_dtor(php_resource_factory_t *f, void *handle)
Destroy (and free) the resource.
Definition: php_raphf_api.c:120
void * php_resource_factory_handle_copy(php_resource_factory_t *f, void *handle)
Create a copy of the resource handle.
Definition: php_raphf_api.c:111
struct php_persistent_handle_provider php_persistent_handle_provider_t
Definition of a persistent handle provider.
php_persistent_handle_wakeup_t wakeup
The persistent handle wakeup routine; may be NULL.
Definition: php_raphf_api.h:200
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.
Definition: php_raphf_api.c:57
zend_bool php_resource_factory_is_persistent(php_resource_factory_t *a)
Check whether a resource factory is a persistent handle resource factory.
Definition: php_raphf_api.c:136
struct php_resource_factory_ops php_resource_factory_ops_t
The resource ops consisting of a ctor, a copy ctor and a dtor.
php_resource_factory_ops_t fops
The resource ops.
Definition: php_raphf_api.h:64
void * php_persistent_handle_accrete(php_persistent_handle_factory_t *a, void *handle)
Copy a persistent handle.
Definition: php_raphf_api.c:445