From: Michael Wallner Date: Wed, 30 Sep 2015 12:35:11 +0000 (+0200) Subject: standardization X-Git-Tag: release-1.1.1RC1~6 X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=b1022d895db9be6ad9cfb43ad70bea0a829eba61;p=m6w6%2Fext-raphf standardization --- diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..9b444ae --- /dev/null +++ b/.editorconfig @@ -0,0 +1,23 @@ +; see http://editorconfig.org +root = true + +[*] +end_of_line = lf +insert_final_newline = true +indent_style = tab +charset = utf-8 +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false + +[*.json] +indent_style = space +indent_size = 4 + +[package.xml] +indent_style = space +indent_size = 1 + +[config.w32] +end_of_line = crlf diff --git a/.gitattributes b/.gitattributes index 0c2cd57..b458680 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,2 +1,3 @@ package.xml merge=touch php_raphf.h merge=touch +config.w32 eol=crlf diff --git a/.gitignore b/.gitignore index 076cb14..f24f704 100644 --- a/.gitignore +++ b/.gitignore @@ -3,8 +3,8 @@ *~ /*.tgz /.deps -/*.lo -/*.la +*.lo +*.la /config.[^mw]* /configure* /lib* @@ -21,3 +21,7 @@ /autom4te* /.dep.inc run-tests.php +/.cproject +/.project +.libs/ +/php_raphf_api.h diff --git a/AUTHORS b/AUTHORS new file mode 100644 index 0000000..67bbd91 --- /dev/null +++ b/AUTHORS @@ -0,0 +1 @@ +Michael Wallner diff --git a/BUGS b/BUGS new file mode 100644 index 0000000..75711d2 --- /dev/null +++ b/BUGS @@ -0,0 +1 @@ +Yay, now known and unresolved issues yet! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..968bd44 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this project, and in the interest of +fostering an open and welcoming community, we pledge to respect all people who +contribute through reporting issues, posting feature requests, updating +documentation, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free +experience for everyone, regardless of level of experience, gender, gender +identity and expression, sexual orientation, disability, personal appearance, +body size, race, ethnicity, age, religion, or nationality. + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery +* Personal attacks +* Trolling or insulting/derogatory comments +* Public or private harassment +* Publishing other's private information, such as physical or electronic + addresses, without explicit permission +* Other unethical or unprofessional conduct. + +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct. By adopting this Code of Conduct, project +maintainers commit themselves to fairly and consistently applying these +principles to every aspect of managing this project. Project maintainers who do +not follow or enforce the Code of Conduct may be permanently removed from the +project team. + +This code of conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by opening an issue or contacting one or more of the project maintainers. + +This Code of Conduct is adapted from the +[Contributor Covenant](http://contributor-covenant.org), version 1.2.0, +available at http://contributor-covenant.org/version/1/2/0/. diff --git a/README.md b/README.md index 34f117e..63b3f63 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,48 @@ -# pecl/raphf +# ext-raphf -## About: +[![Build Status](https://travis-ci.org/m6w6/ext-raphf.svg?branch=v1.1.x)](https://travis-ci.org/m6w6/ext-raphf) The "Resource and Persistent Handle Factory" extension provides facilities to manage those in a convenient manner. -## Installation: +## Documentation -This extension is hosted at [PECL](http://pecl.php.net) and can be installed with [PEAR](http://pear.php.net)'s pecl command: +See the [online markdown reference](https://mdref.m6w6.name/raphf). - # pecl install raphf +Known issues are listed in [BUGS](./BUGS) and future ideas can be found in [TODO](./TODO). -Also, watch out for self-installing [pharext](https://github.com/m6w6/pharext) packages attached to [releases](https://github.com/m6w6/ext-raphf/releases). +## Installing +### PECL -## INI Directives: + pecl install raphf -* raphf.persistent_handle.limit = -1 - The per process/thread persistent handle limit. +### PHARext -## Internals: +Watch out for [PECL replicates](https://replicator.pharext.org?raphf) +and pharext packages attached to [releases](./releases). -> ***NOTE:*** - This extension mostly only provides infrastructure for other extensions. - See the [API docs here](http://m6w6.github.io/ext-raphf/). +### Checkout -## Documentation: + git clone github.com:m6w6/ext-raphf + cd ext-raphf + /path/to/phpize + ./configure --with-php-config=/path/to/php-config + make + sudo make install -Userland documentation can be found at https://mdref.m6w6.name/raphf +## ChangeLog + +A comprehensive list of changes can be obtained from the +[PECL website](https://pecl.php.net/package-changelog.php?package=raphf). + +## License + +ext-raphf is licensed under the 2-Clause-BSD license, which can be found in +the accompanying [LICENSE](./LICENSE) file. + +## Contributing + +All forms of contribution are welcome! Please see the bundled +[CONTRIBUTING](./CONTRIBUTING.md) note for the general principles followed. + +The list of past and current contributors is maintained in [THANKS](./THANKS). diff --git a/THANKS b/THANKS new file mode 100644 index 0000000..8167585 --- /dev/null +++ b/THANKS @@ -0,0 +1,4 @@ +Thanks go to the following people, who have contributed to this project: + +Anatol Belski +Remi Collet diff --git a/config.m4 b/config.m4 index 13d3b83..3b883c8 100644 --- a/config.m4 +++ b/config.m4 @@ -1,7 +1 @@ -PHP_ARG_ENABLE(raphf, whether to enable raphf support, -[ --enable-raphf Enable resource and persistent handles factory support]) - -if test "$PHP_RAPHF" != "no"; then - PHP_INSTALL_HEADERS(ext/raphf, php_raphf.h php_raphf_api.h) - PHP_NEW_EXTENSION(raphf, php_raphf.c, $ext_shared) -fi +sinclude(config0.m4) diff --git a/config.w32 b/config.w32 index 5bdf84e..939cc1b 100644 --- a/config.w32 +++ b/config.w32 @@ -1,10 +1,15 @@ - - -ARG_ENABLE("raphf", "for raphf support", "no"); - -if (PHP_RAPHF == "yes") { - EXTENSION("raphf", "php_raphf.c"); - - AC_DEFINE("HAVE_RAPHF", 1); - PHP_INSTALL_HEADERS("ext/raphf", "php_raphf.h"); -} +ARG_ENABLE("raphf", "for raphf support", "no"); + +if (PHP_RAPHF == "yes") { + var PHP_RAPHF_HEADERS=glob("src/*.h"), PHP_RAPHF_SOURCES=glob("src/*.c"); + + EXTENSION("raphf", PHP_RAPHF_SOURCES); + PHP_INSTALL_HEADERS("ext/raphf", "php_propro.h"); + for (var i=0; i - ]]> - - - - - - - - + + + + + + + + + + + + + + + + + + diff --git a/php_raphf.c b/php_raphf.c deleted file mode 100644 index 1de0fc0..0000000 --- a/php_raphf.c +++ /dev/null @@ -1,715 +0,0 @@ -/* - +--------------------------------------------------------------------+ - | PECL :: raphf | - +--------------------------------------------------------------------+ - | Redistribution and use in source and binary forms, with or without | - | modification, are permitted provided that the conditions mentioned | - | in the accompanying LICENSE file are met. | - +--------------------------------------------------------------------+ - | Copyright (c) 2013, Michael Wallner | - +--------------------------------------------------------------------+ -*/ - -#ifdef HAVE_CONFIG_H -# include "config.h" -#endif - -#include "php.h" -#include "php_ini.h" -#include "ext/standard/info.h" -#include "php_raphf.h" - -struct php_persistent_handle_globals { - ulong limit; - HashTable hash; -}; - -ZEND_BEGIN_MODULE_GLOBALS(raphf) - struct php_persistent_handle_globals persistent_handle; -ZEND_END_MODULE_GLOBALS(raphf) - -#ifdef ZTS -# define PHP_RAPHF_G ((zend_raphf_globals *) \ - (*((void ***) tsrm_ls))[TSRM_UNSHUFFLE_RSRC_ID(raphf_globals_id)]) -#else -# define PHP_RAPHF_G (&raphf_globals) -#endif - -ZEND_DECLARE_MODULE_GLOBALS(raphf) - -#if PHP_VERSION_ID < 50500 -#undef SUCCESS -#undef FAILURE -typedef enum { - SUCCESS = 0, - FAILURE = -1 -} ZEND_RESULT_CODE; -#endif - -#ifndef PHP_RAPHF_DEBUG_PHANDLES -# define PHP_RAPHF_DEBUG_PHANDLES 0 -#endif -#if PHP_RAPHF_DEBUG_PHANDLES -# undef inline -# define inline -#endif - -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)) -{ - if (!f) { - f = emalloc(sizeof(*f)); - } - memset(f, 0, sizeof(*f)); - - memcpy(&f->fops, fops, sizeof(*fops)); - - f->data = data; - f->dtor = dtor; - - f->refcount = 1; - - return f; -} - -unsigned php_resource_factory_addref(php_resource_factory_t *rf) -{ - return ++rf->refcount; -} - -void php_resource_factory_dtor(php_resource_factory_t *f) -{ - --f->refcount; - - if (!f->refcount) { - if (f->dtor) { - f->dtor(f->data); - } - } -} - -void php_resource_factory_free(php_resource_factory_t **f) -{ - if (*f) { - php_resource_factory_dtor(*f); - if (!(*f)->refcount) { - efree(*f); - *f = NULL; - } - } -} - -void *php_resource_factory_handle_ctor(php_resource_factory_t *f, - void *init_arg TSRMLS_DC) -{ - if (f->fops.ctor) { - return f->fops.ctor(f->data, init_arg TSRMLS_CC); - } - return NULL; -} - -void *php_resource_factory_handle_copy(php_resource_factory_t *f, - void *handle TSRMLS_DC) -{ - if (f->fops.copy) { - return f->fops.copy(f->data, handle TSRMLS_CC); - } - return NULL; -} - -void php_resource_factory_handle_dtor(php_resource_factory_t *f, - void *handle TSRMLS_DC) -{ - if (f->fops.dtor) { - f->fops.dtor(f->data, handle TSRMLS_CC); - } -} - -php_resource_factory_t *php_persistent_handle_resource_factory_init( - php_resource_factory_t *a, php_persistent_handle_factory_t *pf) -{ - return php_resource_factory_init(a, - php_persistent_handle_get_resource_factory_ops(), pf, - (void(*)(void*)) php_persistent_handle_abandon); -} - -zend_bool php_resource_factory_is_persistent(php_resource_factory_t *a) -{ - return a->dtor == (void(*)(void *)) php_persistent_handle_abandon; -} - - -static inline php_persistent_handle_list_t *php_persistent_handle_list_init( - php_persistent_handle_list_t *list) -{ - int free_list; - - if ((free_list = !list)) { - list = pemalloc(sizeof(php_persistent_handle_list_t), 1); - } - - list->used = 0; - - if (SUCCESS != zend_hash_init(&list->free, 0, NULL, NULL, 1)) { - if (free_list) { - pefree(list, 1); - } - list = NULL; - } - - return list; -} - -static int php_persistent_handle_apply_stat(void *p TSRMLS_DC, int argc, - va_list argv, zend_hash_key *key) -{ - php_persistent_handle_list_t **list = p; - zval *zsubentry, *zentry = va_arg(argv, zval *); - - MAKE_STD_ZVAL(zsubentry); - array_init(zsubentry); - add_assoc_long_ex(zsubentry, ZEND_STRS("used"), (*list)->used); - add_assoc_long_ex(zsubentry, ZEND_STRS("free"), - zend_hash_num_elements(&(*list)->free)); - add_assoc_zval_ex(zentry, key->arKey, key->nKeyLength, zsubentry); - - return ZEND_HASH_APPLY_KEEP; -} - -static int php_persistent_handle_apply_statall(void *p TSRMLS_DC, int argc, - va_list argv, zend_hash_key *key) -{ - php_persistent_handle_provider_t *provider = p; - HashTable *ht = va_arg(argv, HashTable *); - zval *zentry; - - MAKE_STD_ZVAL(zentry); - array_init(zentry); - - zend_hash_apply_with_arguments(&provider->list.free TSRMLS_CC, - php_persistent_handle_apply_stat, 1, zentry); - zend_symtable_update(ht, key->arKey, key->nKeyLength, &zentry, - sizeof(zval *), NULL); - - return ZEND_HASH_APPLY_KEEP; -} - -static int php_persistent_handle_apply_cleanup_ex(void *pp, void *arg TSRMLS_DC) -{ - php_resource_factory_t *rf = arg; - void **handle = pp; - -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "DESTROY: %p\n", *handle); -#endif - php_resource_factory_handle_dtor(rf, *handle TSRMLS_CC); - return ZEND_HASH_APPLY_REMOVE; -} - -static int php_persistent_handle_apply_cleanup(void *pp, void *arg TSRMLS_DC) -{ - php_resource_factory_t *rf = arg; - php_persistent_handle_list_t **listp = pp; - - zend_hash_apply_with_argument(&(*listp)->free, - php_persistent_handle_apply_cleanup_ex, rf TSRMLS_CC); - if ((*listp)->used) { - return ZEND_HASH_APPLY_KEEP; - } - zend_hash_destroy(&(*listp)->free); -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "LSTFREE: %p\n", *listp); -#endif - pefree(*listp, 1); - *listp = NULL; - return ZEND_HASH_APPLY_REMOVE; -} - -static inline void php_persistent_handle_list_dtor( - php_persistent_handle_list_t *list, - php_persistent_handle_provider_t *provider TSRMLS_DC) -{ -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "LSTDTOR: %p\n", list); -#endif - zend_hash_apply_with_argument(&list->free, - php_persistent_handle_apply_cleanup_ex, &provider->rf TSRMLS_CC); - zend_hash_destroy(&list->free); -} - -static inline void php_persistent_handle_list_free( - php_persistent_handle_list_t **list, - php_persistent_handle_provider_t *provider TSRMLS_DC) -{ - php_persistent_handle_list_dtor(*list, provider TSRMLS_CC); -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "LSTFREE: %p\n", *list); -#endif - pefree(*list, 1); - *list = NULL; -} - -static int php_persistent_handle_list_apply_dtor(void *listp, - void *provider TSRMLS_DC) -{ - php_persistent_handle_list_free(listp, provider TSRMLS_CC); - return ZEND_HASH_APPLY_REMOVE; -} - -static inline php_persistent_handle_list_t *php_persistent_handle_list_find( - php_persistent_handle_provider_t *provider, const char *ident_str, - size_t ident_len TSRMLS_DC) -{ - php_persistent_handle_list_t **list, *new_list; - ZEND_RESULT_CODE rv = zend_symtable_find(&provider->list.free, ident_str, - ident_len + 1, (void *) &list); - - if (SUCCESS == rv) { -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "LSTFIND: %p\n", *list); -#endif - return *list; - } - - if ((new_list = php_persistent_handle_list_init(NULL))) { - rv = zend_symtable_update(&provider->list.free, ident_str, ident_len+1, - (void *) &new_list, sizeof(php_persistent_handle_list_t *), - (void *) &list); - if (SUCCESS == rv) { -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "LSTFIND: %p (new)\n", *list); -#endif - return *list; - } - php_persistent_handle_list_free(&new_list, provider TSRMLS_CC); - } - - return NULL; -} - -static int php_persistent_handle_apply_cleanup_all(void *p TSRMLS_DC, int argc, - va_list argv, zend_hash_key *key) -{ - php_persistent_handle_provider_t *provider = p; - const char *ident_str = va_arg(argv, const char *); - size_t ident_len = va_arg(argv, size_t); - php_persistent_handle_list_t *list; - - if (ident_str && ident_len) { - if ((list = php_persistent_handle_list_find(provider, ident_str, - ident_len TSRMLS_CC))) { - zend_hash_apply_with_argument(&list->free, - php_persistent_handle_apply_cleanup_ex, - &provider->rf TSRMLS_CC); - } - } else { - zend_hash_apply_with_argument(&provider->list.free, - php_persistent_handle_apply_cleanup, &provider->rf TSRMLS_CC); - } - - return ZEND_HASH_APPLY_KEEP; -} - -static void php_persistent_handle_hash_dtor(void *p) -{ - php_persistent_handle_provider_t *provider; - TSRMLS_FETCH(); - - provider = (php_persistent_handle_provider_t *) p; - zend_hash_apply_with_argument(&provider->list.free, - php_persistent_handle_list_apply_dtor, provider TSRMLS_CC); - zend_hash_destroy(&provider->list.free); - php_resource_factory_dtor(&provider->rf); -} - -PHP_RAPHF_API 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 *) TSRMLS_DC) -{ - ZEND_RESULT_CODE status = FAILURE; - php_persistent_handle_provider_t provider; - - if (php_persistent_handle_list_init(&provider.list)) { - if (php_resource_factory_init(&provider.rf, fops, data, dtor)) { -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "PROVIDE: %p %s\n", PHP_RAPHF_G, name_str); -#endif - - status = zend_symtable_update(&PHP_RAPHF_G->persistent_handle.hash, - name_str, name_len+1, (void *) &provider, - sizeof(php_persistent_handle_provider_t), NULL); - if (SUCCESS != status) { - php_resource_factory_dtor(&provider.rf); - } - } - } - - return status; -} - -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 TSRMLS_DC) -{ - ZEND_RESULT_CODE status = FAILURE; - php_persistent_handle_factory_t *free_a = NULL; - - if (!a) { - free_a = a = emalloc(sizeof(*a)); - } - memset(a, 0, sizeof(*a)); - - status = zend_symtable_find(&PHP_RAPHF_G->persistent_handle.hash, name_str, - name_len+1, (void *) &a->provider); - - if (SUCCESS == status) { - a->ident.str = estrndup(ident_str, ident_len); - a->ident.len = ident_len; - - a->wakeup = wakeup; - a->retire = retire; - - if (free_a) { - a->free_on_abandon = 1; - } - } else { - if (free_a) { - efree(free_a); - } - a = NULL; - } - -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "CONCEDE: %p %p (%s) (%s)\n", PHP_RAPHF_G, - a ? a->provider : NULL, name_str, ident_str); -#endif - - return a; -} - -PHP_RAPHF_API void php_persistent_handle_abandon( - php_persistent_handle_factory_t *a) -{ - zend_bool f = a->free_on_abandon; - -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "ABANDON: %p\n", a->provider); -#endif - - STR_FREE(a->ident.str); - memset(a, 0, sizeof(*a)); - if (f) { - efree(a); - } -} - -void *php_persistent_handle_acquire( - php_persistent_handle_factory_t *a, void *init_arg TSRMLS_DC) -{ - int key; - ZEND_RESULT_CODE rv; - ulong index; - void **handle_ptr, *handle = NULL; - php_persistent_handle_list_t *list; - - list = php_persistent_handle_list_find(a->provider, a->ident.str, - a->ident.len TSRMLS_CC); - if (list) { - zend_hash_internal_pointer_end(&list->free); - key = zend_hash_get_current_key(&list->free, NULL, &index, 0); - rv = zend_hash_get_current_data(&list->free, (void *) &handle_ptr); - if (HASH_KEY_NON_EXISTANT != key && SUCCESS == rv) { - handle = *handle_ptr; - if (a->wakeup) { - a->wakeup(a, &handle TSRMLS_CC); - } - zend_hash_index_del(&list->free, index); - } else { - handle = php_resource_factory_handle_ctor(&a->provider->rf, - init_arg TSRMLS_CC); - } -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "CREATED: %p\n", *handle); -#endif - if (handle) { - ++a->provider->list.used; - ++list->used; - } - } - - return handle; -} - -void *php_persistent_handle_accrete( - php_persistent_handle_factory_t *a, void *handle TSRMLS_DC) -{ - void *new_handle = NULL; - php_persistent_handle_list_t *list; - - new_handle = php_resource_factory_handle_copy(&a->provider->rf, - handle TSRMLS_CC); - if (handle) { - list = php_persistent_handle_list_find(a->provider, a->ident.str, - a->ident.len TSRMLS_CC); - if (list) { - ++list->used; - } - ++a->provider->list.used; - } - - return new_handle; -} - -void php_persistent_handle_release( - php_persistent_handle_factory_t *a, void *handle TSRMLS_DC) -{ - php_persistent_handle_list_t *list; - - list = php_persistent_handle_list_find(a->provider, a->ident.str, - a->ident.len TSRMLS_CC); - if (list) { - if (a->provider->list.used >= PHP_RAPHF_G->persistent_handle.limit) { -#if PHP_RAPHF_DEBUG_PHANDLES - fprintf(stderr, "DESTROY: %p\n", *handle); -#endif - php_resource_factory_handle_dtor(&a->provider->rf, - handle TSRMLS_CC); - } else { - if (a->retire) { - a->retire(a, &handle TSRMLS_CC); - } - zend_hash_next_index_insert(&list->free, (void *) &handle, - sizeof(void *), NULL); - } - - --a->provider->list.used; - --list->used; - } -} - -void php_persistent_handle_cleanup(const char *name_str, size_t name_len, - const char *ident_str, size_t ident_len TSRMLS_DC) -{ - php_persistent_handle_provider_t *provider; - php_persistent_handle_list_t *list; - ZEND_RESULT_CODE rv; - - if (name_str && name_len) { - rv = zend_symtable_find(&PHP_RAPHF_G->persistent_handle.hash, name_str, - name_len+1, (void *) &provider); - - if (SUCCESS == rv) { - if (ident_str && ident_len) { - list = php_persistent_handle_list_find(provider, ident_str, - ident_len TSRMLS_CC); - if (list) { - zend_hash_apply_with_argument(&list->free, - php_persistent_handle_apply_cleanup_ex, - &provider->rf TSRMLS_CC); - } - } else { - zend_hash_apply_with_argument(&provider->list.free, - php_persistent_handle_apply_cleanup, - &provider->rf TSRMLS_CC); - } - } - } else { - zend_hash_apply_with_arguments( - &PHP_RAPHF_G->persistent_handle.hash TSRMLS_CC, - php_persistent_handle_apply_cleanup_all, 2, ident_str, - ident_len); - } -} - -HashTable *php_persistent_handle_statall(HashTable *ht TSRMLS_DC) -{ - if (zend_hash_num_elements(&PHP_RAPHF_G->persistent_handle.hash)) { - if (!ht) { - ALLOC_HASHTABLE(ht); - zend_hash_init(ht, 0, NULL, ZVAL_PTR_DTOR, 0); - } - zend_hash_apply_with_arguments( - &PHP_RAPHF_G->persistent_handle.hash TSRMLS_CC, - php_persistent_handle_apply_statall, 1, ht); - } else if (ht) { - ht = NULL; - } - - return ht; -} - -static php_resource_factory_ops_t php_persistent_handle_resource_factory_ops = { - (php_resource_factory_handle_ctor_t) php_persistent_handle_acquire, - (php_resource_factory_handle_copy_t) php_persistent_handle_accrete, - (php_resource_factory_handle_dtor_t) php_persistent_handle_release -}; - -php_resource_factory_ops_t *php_persistent_handle_get_resource_factory_ops(void) -{ - return &php_persistent_handle_resource_factory_ops; -} - -ZEND_BEGIN_ARG_INFO_EX(ai_raphf_stat_persistent_handles, 0, 0, 0) -ZEND_END_ARG_INFO(); -static PHP_FUNCTION(raphf_stat_persistent_handles) -{ - if (SUCCESS == zend_parse_parameters_none()) { - object_init(return_value); - if (php_persistent_handle_statall(HASH_OF(return_value) TSRMLS_CC)) { - return; - } - zval_dtor(return_value); - } - RETURN_FALSE; -} - -ZEND_BEGIN_ARG_INFO_EX(ai_raphf_clean_persistent_handles, 0, 0, 0) - ZEND_ARG_INFO(0, name) - ZEND_ARG_INFO(0, ident) -ZEND_END_ARG_INFO(); -static PHP_FUNCTION(raphf_clean_persistent_handles) -{ - char *name_str = NULL, *ident_str = NULL; - int name_len = 0, ident_len = 0; - - if (SUCCESS == zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "|s!s!", - &name_str, &name_len, &ident_str, &ident_len)) { - php_persistent_handle_cleanup(name_str, name_len, ident_str, - ident_len TSRMLS_CC); - } -} - -static const zend_function_entry raphf_functions[] = { - ZEND_NS_FENTRY("raphf", stat_persistent_handles, - ZEND_FN(raphf_stat_persistent_handles), - ai_raphf_stat_persistent_handles, 0) - ZEND_NS_FENTRY("raphf", clean_persistent_handles, - ZEND_FN(raphf_clean_persistent_handles), - ai_raphf_clean_persistent_handles, 0) - {0} -}; - -PHP_INI_BEGIN() - STD_PHP_INI_ENTRY("raphf.persistent_handle.limit", "-1", PHP_INI_SYSTEM, - OnUpdateLong, persistent_handle.limit, zend_raphf_globals, - raphf_globals) -PHP_INI_END() - -static HashTable *php_persistent_handles_global_hash; - -static PHP_GINIT_FUNCTION(raphf) -{ - raphf_globals->persistent_handle.limit = -1; - - zend_hash_init(&raphf_globals->persistent_handle.hash, 0, NULL, - php_persistent_handle_hash_dtor, 1); - if (php_persistent_handles_global_hash) { - zend_hash_copy(&raphf_globals->persistent_handle.hash, - php_persistent_handles_global_hash, NULL, NULL, - sizeof(php_persistent_handle_provider_t)); - } -} - -static PHP_GSHUTDOWN_FUNCTION(raphf) -{ - zend_hash_destroy(&raphf_globals->persistent_handle.hash); -} - -PHP_MINIT_FUNCTION(raphf) -{ - php_persistent_handles_global_hash = &PHP_RAPHF_G->persistent_handle.hash; - REGISTER_INI_ENTRIES(); - return SUCCESS; -} - -PHP_MSHUTDOWN_FUNCTION(raphf) -{ - UNREGISTER_INI_ENTRIES(); - php_persistent_handles_global_hash = NULL; - return SUCCESS; -} - -static int php_persistent_handle_apply_info_ex(void *p TSRMLS_DC, int argc, - va_list argv, zend_hash_key *key) -{ - php_persistent_handle_list_t **list = p; - zend_hash_key *super_key = va_arg(argv, zend_hash_key *); - char used[21], free[21]; - - slprintf(used, sizeof(used), "%u", (*list)->used); - slprintf(free, sizeof(free), "%d", zend_hash_num_elements(&(*list)->free)); - - php_info_print_table_row(4, super_key->arKey, key->arKey, used, free); - - return ZEND_HASH_APPLY_KEEP; -} - -static int php_persistent_handle_apply_info(void *p TSRMLS_DC, int argc, - va_list argv, zend_hash_key *key) -{ - php_persistent_handle_provider_t *provider = p; - - zend_hash_apply_with_arguments(&provider->list.free TSRMLS_CC, - php_persistent_handle_apply_info_ex, 1, key); - - return ZEND_HASH_APPLY_KEEP; -} - -PHP_MINFO_FUNCTION(raphf) -{ - php_info_print_table_start(); - php_info_print_table_header(2, - "Resource and persistent handle factory support", "enabled"); - php_info_print_table_row(2, "Extension version", PHP_RAPHF_VERSION); - php_info_print_table_end(); - - php_info_print_table_start(); - php_info_print_table_colspan_header(4, "Persistent handles in this " -#ifdef ZTS - "thread" -#else - "process" -#endif - ); - php_info_print_table_header(4, "Provider", "Ident", "Used", "Free"); - zend_hash_apply_with_arguments( - &PHP_RAPHF_G->persistent_handle.hash TSRMLS_CC, - php_persistent_handle_apply_info, 0); - php_info_print_table_end(); - - DISPLAY_INI_ENTRIES(); -} - -zend_module_entry raphf_module_entry = { - STANDARD_MODULE_HEADER, - "raphf", - raphf_functions, - PHP_MINIT(raphf), - PHP_MSHUTDOWN(raphf), - NULL, - NULL, - PHP_MINFO(raphf), - PHP_RAPHF_VERSION, - ZEND_MODULE_GLOBALS(raphf), - PHP_GINIT(raphf), - PHP_GSHUTDOWN(raphf), - NULL, - STANDARD_MODULE_PROPERTIES_EX -}; -/* }}} */ - -#ifdef COMPILE_DL_RAPHF -ZEND_GET_MODULE(raphf) -#endif - - -/* - * Local variables: - * tab-width: 4 - * c-basic-offset: 4 - * End: - * vim600: noet sw=4 ts=4 fdm=marker - * vim<600: noet sw=4 ts=4 - */ diff --git a/php_raphf_api.h b/php_raphf_api.h deleted file mode 100644 index 4245c46..0000000 --- a/php_raphf_api.h +++ /dev/null @@ -1,430 +0,0 @@ -/* - +--------------------------------------------------------------------+ - | PECL :: raphf | - +--------------------------------------------------------------------+ - | Redistribution and use in source and binary forms, with or without | - | modification, are permitted provided that the conditions mentioned | - | in the accompanying LICENSE file are met. | - +--------------------------------------------------------------------+ - | Copyright (c) 2013, Michael Wallner | - +--------------------------------------------------------------------+ -*/ - -#ifndef PHP_RAPHF_API_H -#define PHP_RAPHF_API_H - -/** - * A resource constructor. - * - * @param opaque is the \a data from php_persistent_handle_provide() - * @param init_arg is the \a init_arg from php_resource_factory_init() - * @return the created (persistent) handle - */ -typedef void *(*php_resource_factory_handle_ctor_t)(void *opaque, - void *init_arg TSRMLS_DC); - -/** - * The copy constructor of a resource. - * - * @param opaque the factory's data - * @param handle the (persistent) handle to copy - */ -typedef void *(*php_resource_factory_handle_copy_t)(void *opaque, - void *handle TSRMLS_DC); - -/** - * The destructor of a resource. - * - * @param opaque the factory's data - * @param handle the handle to destroy - */ -typedef void (*php_resource_factory_handle_dtor_t)(void *opaque, - void *handle TSRMLS_DC); - -/** - * 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_ops { - /** The resource constructor */ - php_resource_factory_handle_ctor_t ctor; - /** The resource's copy constructor */ - php_resource_factory_handle_copy_t copy; - /** The resource's destructor */ - php_resource_factory_handle_dtor_t dtor; -} php_resource_factory_ops_t; - -/** - * The resource factory. - */ -typedef struct php_resource_factory { - /** The resource ops */ - php_resource_factory_ops_t fops; - /** Opaque user data */ - void *data; - /** User data destructor */ - void (*dtor)(void *data); - /** How often this factory is referenced */ - unsigned refcount; -} php_resource_factory_t; - -/** - * Initialize a resource factory. - * - * If you register a \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. - * - * @param f the factory to initialize; if NULL allocated on the heap - * @param fops the resource ops to assign to the factory - * @param data opaque user data; may be NULL - * @param dtor a destructor for the data; may be NULL - * @return \a f or an allocated resource factory - */ -PHP_RAPHF_API 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)); - -/** - * Increase the refcount of the resource factory. - * - * @param rf the resource factory - * @return the new refcount - */ -PHP_RAPHF_API unsigned php_resource_factory_addref(php_resource_factory_t *rf); - -/** - * Destroy the resource factory. - * - * If the factory's refcount reaches 0, the \a dtor for \a data is called. - * - * @param f the resource factory - */ -PHP_RAPHF_API void php_resource_factory_dtor(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. - * - * @param f the resource factory - */ -PHP_RAPHF_API void php_resource_factory_free(php_resource_factory_t **f); - -/** - * Construct a resource by the resource factory \a f - * - * @param f the resource factory - * @param init_arg for the resource constructor - * @return the new resource - */ -PHP_RAPHF_API void *php_resource_factory_handle_ctor(php_resource_factory_t *f, - void *init_arg TSRMLS_DC); - -/** - * Create a copy of the resource \a handle - * - * @param f the resource factory - * @param handle the resource to copy - * @return the copy - */ -PHP_RAPHF_API void *php_resource_factory_handle_copy(php_resource_factory_t *f, - void *handle TSRMLS_DC); - -/** - * Destroy (and free) the resource - * - * @param f the resource factory - * @param handle the resource to destroy - */ -PHP_RAPHF_API void php_resource_factory_handle_dtor(php_resource_factory_t *f, - void *handle TSRMLS_DC); - -/** - * Persistent handles storage - */ -typedef struct php_persistent_handle_list { - /** Storage of free resources */ - HashTable free; - /** Count of acquired resources */ - ulong used; -} php_persistent_handle_list_t; - -/** - * Definition of a persistent handle provider. - * Holds a resource factory an a persistent handle list. - */ -typedef struct php_persistent_handle_provider { - /** - * The list of free handles. - * Hash of "ident" => array(handles) entries. Persistent handles are - * acquired out of this list. - */ - php_persistent_handle_list_t list; - - /** - * The resource factory. - * New handles are created by this factory. - */ - php_resource_factory_t rf; -} php_persistent_handle_provider_t; - -typedef struct php_persistent_handle_factory php_persistent_handle_factory_t; - -/** - * Wakeup the persistent handle on re-acquisition. - */ -typedef void (*php_persistent_handle_wakeup_t)( - php_persistent_handle_factory_t *f, void **handle TSRMLS_DC); -/** - * Retire the persistent handle on release. - */ -typedef void (*php_persistent_handle_retire_t)( - php_persistent_handle_factory_t *f, void **handle TSRMLS_DC); - -/** - * 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 \a name_str has - * been registered with php_persistent_handle_provide(). - */ -struct php_persistent_handle_factory { - /** The persistent handle provider */ - php_persistent_handle_provider_t *provider; - /** The persistent handle wakeup routine; may be NULL */ - php_persistent_handle_wakeup_t wakeup; - /** The persistent handle retire routine; may be NULL */ - php_persistent_handle_retire_t retire; - - /** The ident for which this factory manages resources */ - struct { - /** ident string */ - char *str; - /** ident length */ - size_t len; - } ident; - - /** Whether it has to be free'd on php_persistent_handle_abandon() */ - unsigned free_on_abandon:1; -}; - -/** - * Register a persistent handle provider in MINIT. - * - * Registers a factory provider for \a name_str with \a fops resource factory - * ops. Call this in your MINIT. - * - * A php_resource_factory will be created with \a fops, \a data and \a 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. - * - * @param name_str the provider name, e.g. "http\Client\Curl" - * @param name_len the provider name length, e.g. strlen("http\Client\Curl") - * @param fops the resource factory ops - * @param data opaque user data - * @param dtor \a data destructor - * @return SUCCESS/FAILURE - */ -PHP_RAPHF_API int /* SUCCESS|FAILURE */ php_persistent_handle_provide( - const char *name_str, size_t name_len, php_resource_factory_ops_t *fops, - void *data, void (*dtor)(void *) TSRMLS_DC); - -/** - * Retrieve a persistent handle factory at runtime. - * - * If a persistent handle provider has been registered for \a name_str, a new - * php_persistent_handle_factory creating resources in the \a ident_str - * namespace will be constructed. - * - * The wakeup routine \a wakeup and the retire routine \a retire will be - * assigned to the new php_persistent_handle_factory. - * - * @param a pointer to a factory; allocated on the heap if NULL - * @param name_str the provider name, e.g. "http\Client\Curl" - * @param name_len the provider name length, e.g. strlen("http\Client\Curl") - * @param ident_str the subsidiary namespace, e.g. "php.net:80" - * @param ident_len the subsidiary namespace lenght, e.g. strlen("php.net:80") - * @param wakeup any persistent handle wakeup routine - * @param retire any persistent handle retire routine - * @return \a a or an allocated persistent handle factory - */ -PHP_RAPHF_API 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 TSRMLS_DC); - -/** - * 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. - * - * @param a the persistent handle factory to destroy - */ -PHP_RAPHF_API void php_persistent_handle_abandon( - php_persistent_handle_factory_t *a); - -/** - * 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. - * - * @param a the persistent handle factory - * @param init_arg the \a init_arg for php_resource_factory_handle_ctor() - * @return the acquired resource - */ -PHP_RAPHF_API void *php_persistent_handle_acquire( - php_persistent_handle_factory_t *a, void *init_arg TSRMLS_DC); - -/** - * 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. - * - * @param a the persistent handle factory - * @param handle the handle to release - */ -PHP_RAPHF_API void php_persistent_handle_release( - php_persistent_handle_factory_t *a, void *handle TSRMLS_DC); - -/** - * Copy a persistent handle. - * - * Let the underlying resource factory copy the \a handle. - * - * @param a the persistent handle factory - * @param handle the resource to accrete - */ -PHP_RAPHF_API void *php_persistent_handle_accrete( - php_persistent_handle_factory_t *a, void *handle TSRMLS_DC); - -/** - * 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: - * ~~~~~~~~~~~~~~~{.c} - * 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; - * } - * ~~~~~~~~~~~~~~~ - */ -PHP_RAPHF_API php_resource_factory_ops_t * -php_persistent_handle_get_resource_factory_ops(void); - -/** - * Create a resource factory for persistent handles. - * - * This will create a resource factory with persistent handle ops, which wraps - * the provided reource factory \a pf. - * - * @param a the persistent handle resource factory to initialize - * @param pf the resource factory to wrap - */ -PHP_RAPHF_API php_resource_factory_t * -php_persistent_handle_resource_factory_init(php_resource_factory_t *a, - php_persistent_handle_factory_t *pf); - -/** - * Check whether a resource factory is a persistent handle resource factory. - * - * @param a the resource factory to check - */ -PHP_RAPHF_API zend_bool php_resource_factory_is_persistent( - php_resource_factory_t *a); - -/** - * Clean persistent handles up. - * - * Destroy persistent handles of provider \a name_str and in subsidiary - * namespace \a ident_str. - * - * If \a name_str is NULL, all persistent handles of all providers with a - * matching \a ident_str will be cleaned up. - * - * If \a ident_str is NULL all persistent handles of the provider will be - * cleaned up. - * - * Ergo, if both, \a name_str and \a 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. - * - * @param name_str the provider name; may be NULL - * @param name_len the provider name length - * @param ident_str the subsidiary namespace name; may be NULL - * @param ident_len the subsidiary namespace name length - */ -PHP_RAPHF_API void php_persistent_handle_cleanup(const char *name_str, - size_t name_len, const char *ident_str, size_t ident_len TSRMLS_DC); - -/** - * Retrieve statistics about the current process/thread's persistent handles. - * - * @return a HashTable like: - * ~~~~~~~~~~~~~~~ - * [ - * "name" => [ - * "ident" => [ - * "used" => 1, - * "free" => 0, - * ] - * ] - * ] - * ~~~~~~~~~~~~~~~ - */ -PHP_RAPHF_API HashTable *php_persistent_handle_statall(HashTable *ht TSRMLS_DC); - -#endif /* PHP_RAPHF_API_H */ - - -/* - * Local variables: - * tab-width: 4 - * c-basic-offset: 4 - * End: - * vim600: noet sw=4 ts=4 fdm=marker - * vim<600: noet sw=4 ts=4 - */ diff --git a/src/php_raphf_api.c b/src/php_raphf_api.c new file mode 100644 index 0000000..1de0fc0 --- /dev/null +++ b/src/php_raphf_api.c @@ -0,0 +1,715 @@ +/* + +--------------------------------------------------------------------+ + | PECL :: raphf | + +--------------------------------------------------------------------+ + | Redistribution and use in source and binary forms, with or without | + | modification, are permitted provided that the conditions mentioned | + | in the accompanying LICENSE file are met. | + +--------------------------------------------------------------------+ + | Copyright (c) 2013, Michael Wallner | + +--------------------------------------------------------------------+ +*/ + +#ifdef HAVE_CONFIG_H +# include "config.h" +#endif + +#include "php.h" +#include "php_ini.h" +#include "ext/standard/info.h" +#include "php_raphf.h" + +struct php_persistent_handle_globals { + ulong limit; + HashTable hash; +}; + +ZEND_BEGIN_MODULE_GLOBALS(raphf) + struct php_persistent_handle_globals persistent_handle; +ZEND_END_MODULE_GLOBALS(raphf) + +#ifdef ZTS +# define PHP_RAPHF_G ((zend_raphf_globals *) \ + (*((void ***) tsrm_ls))[TSRM_UNSHUFFLE_RSRC_ID(raphf_globals_id)]) +#else +# define PHP_RAPHF_G (&raphf_globals) +#endif + +ZEND_DECLARE_MODULE_GLOBALS(raphf) + +#if PHP_VERSION_ID < 50500 +#undef SUCCESS +#undef FAILURE +typedef enum { + SUCCESS = 0, + FAILURE = -1 +} ZEND_RESULT_CODE; +#endif + +#ifndef PHP_RAPHF_DEBUG_PHANDLES +# define PHP_RAPHF_DEBUG_PHANDLES 0 +#endif +#if PHP_RAPHF_DEBUG_PHANDLES +# undef inline +# define inline +#endif + +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)) +{ + if (!f) { + f = emalloc(sizeof(*f)); + } + memset(f, 0, sizeof(*f)); + + memcpy(&f->fops, fops, sizeof(*fops)); + + f->data = data; + f->dtor = dtor; + + f->refcount = 1; + + return f; +} + +unsigned php_resource_factory_addref(php_resource_factory_t *rf) +{ + return ++rf->refcount; +} + +void php_resource_factory_dtor(php_resource_factory_t *f) +{ + --f->refcount; + + if (!f->refcount) { + if (f->dtor) { + f->dtor(f->data); + } + } +} + +void php_resource_factory_free(php_resource_factory_t **f) +{ + if (*f) { + php_resource_factory_dtor(*f); + if (!(*f)->refcount) { + efree(*f); + *f = NULL; + } + } +} + +void *php_resource_factory_handle_ctor(php_resource_factory_t *f, + void *init_arg TSRMLS_DC) +{ + if (f->fops.ctor) { + return f->fops.ctor(f->data, init_arg TSRMLS_CC); + } + return NULL; +} + +void *php_resource_factory_handle_copy(php_resource_factory_t *f, + void *handle TSRMLS_DC) +{ + if (f->fops.copy) { + return f->fops.copy(f->data, handle TSRMLS_CC); + } + return NULL; +} + +void php_resource_factory_handle_dtor(php_resource_factory_t *f, + void *handle TSRMLS_DC) +{ + if (f->fops.dtor) { + f->fops.dtor(f->data, handle TSRMLS_CC); + } +} + +php_resource_factory_t *php_persistent_handle_resource_factory_init( + php_resource_factory_t *a, php_persistent_handle_factory_t *pf) +{ + return php_resource_factory_init(a, + php_persistent_handle_get_resource_factory_ops(), pf, + (void(*)(void*)) php_persistent_handle_abandon); +} + +zend_bool php_resource_factory_is_persistent(php_resource_factory_t *a) +{ + return a->dtor == (void(*)(void *)) php_persistent_handle_abandon; +} + + +static inline php_persistent_handle_list_t *php_persistent_handle_list_init( + php_persistent_handle_list_t *list) +{ + int free_list; + + if ((free_list = !list)) { + list = pemalloc(sizeof(php_persistent_handle_list_t), 1); + } + + list->used = 0; + + if (SUCCESS != zend_hash_init(&list->free, 0, NULL, NULL, 1)) { + if (free_list) { + pefree(list, 1); + } + list = NULL; + } + + return list; +} + +static int php_persistent_handle_apply_stat(void *p TSRMLS_DC, int argc, + va_list argv, zend_hash_key *key) +{ + php_persistent_handle_list_t **list = p; + zval *zsubentry, *zentry = va_arg(argv, zval *); + + MAKE_STD_ZVAL(zsubentry); + array_init(zsubentry); + add_assoc_long_ex(zsubentry, ZEND_STRS("used"), (*list)->used); + add_assoc_long_ex(zsubentry, ZEND_STRS("free"), + zend_hash_num_elements(&(*list)->free)); + add_assoc_zval_ex(zentry, key->arKey, key->nKeyLength, zsubentry); + + return ZEND_HASH_APPLY_KEEP; +} + +static int php_persistent_handle_apply_statall(void *p TSRMLS_DC, int argc, + va_list argv, zend_hash_key *key) +{ + php_persistent_handle_provider_t *provider = p; + HashTable *ht = va_arg(argv, HashTable *); + zval *zentry; + + MAKE_STD_ZVAL(zentry); + array_init(zentry); + + zend_hash_apply_with_arguments(&provider->list.free TSRMLS_CC, + php_persistent_handle_apply_stat, 1, zentry); + zend_symtable_update(ht, key->arKey, key->nKeyLength, &zentry, + sizeof(zval *), NULL); + + return ZEND_HASH_APPLY_KEEP; +} + +static int php_persistent_handle_apply_cleanup_ex(void *pp, void *arg TSRMLS_DC) +{ + php_resource_factory_t *rf = arg; + void **handle = pp; + +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "DESTROY: %p\n", *handle); +#endif + php_resource_factory_handle_dtor(rf, *handle TSRMLS_CC); + return ZEND_HASH_APPLY_REMOVE; +} + +static int php_persistent_handle_apply_cleanup(void *pp, void *arg TSRMLS_DC) +{ + php_resource_factory_t *rf = arg; + php_persistent_handle_list_t **listp = pp; + + zend_hash_apply_with_argument(&(*listp)->free, + php_persistent_handle_apply_cleanup_ex, rf TSRMLS_CC); + if ((*listp)->used) { + return ZEND_HASH_APPLY_KEEP; + } + zend_hash_destroy(&(*listp)->free); +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "LSTFREE: %p\n", *listp); +#endif + pefree(*listp, 1); + *listp = NULL; + return ZEND_HASH_APPLY_REMOVE; +} + +static inline void php_persistent_handle_list_dtor( + php_persistent_handle_list_t *list, + php_persistent_handle_provider_t *provider TSRMLS_DC) +{ +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "LSTDTOR: %p\n", list); +#endif + zend_hash_apply_with_argument(&list->free, + php_persistent_handle_apply_cleanup_ex, &provider->rf TSRMLS_CC); + zend_hash_destroy(&list->free); +} + +static inline void php_persistent_handle_list_free( + php_persistent_handle_list_t **list, + php_persistent_handle_provider_t *provider TSRMLS_DC) +{ + php_persistent_handle_list_dtor(*list, provider TSRMLS_CC); +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "LSTFREE: %p\n", *list); +#endif + pefree(*list, 1); + *list = NULL; +} + +static int php_persistent_handle_list_apply_dtor(void *listp, + void *provider TSRMLS_DC) +{ + php_persistent_handle_list_free(listp, provider TSRMLS_CC); + return ZEND_HASH_APPLY_REMOVE; +} + +static inline php_persistent_handle_list_t *php_persistent_handle_list_find( + php_persistent_handle_provider_t *provider, const char *ident_str, + size_t ident_len TSRMLS_DC) +{ + php_persistent_handle_list_t **list, *new_list; + ZEND_RESULT_CODE rv = zend_symtable_find(&provider->list.free, ident_str, + ident_len + 1, (void *) &list); + + if (SUCCESS == rv) { +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "LSTFIND: %p\n", *list); +#endif + return *list; + } + + if ((new_list = php_persistent_handle_list_init(NULL))) { + rv = zend_symtable_update(&provider->list.free, ident_str, ident_len+1, + (void *) &new_list, sizeof(php_persistent_handle_list_t *), + (void *) &list); + if (SUCCESS == rv) { +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "LSTFIND: %p (new)\n", *list); +#endif + return *list; + } + php_persistent_handle_list_free(&new_list, provider TSRMLS_CC); + } + + return NULL; +} + +static int php_persistent_handle_apply_cleanup_all(void *p TSRMLS_DC, int argc, + va_list argv, zend_hash_key *key) +{ + php_persistent_handle_provider_t *provider = p; + const char *ident_str = va_arg(argv, const char *); + size_t ident_len = va_arg(argv, size_t); + php_persistent_handle_list_t *list; + + if (ident_str && ident_len) { + if ((list = php_persistent_handle_list_find(provider, ident_str, + ident_len TSRMLS_CC))) { + zend_hash_apply_with_argument(&list->free, + php_persistent_handle_apply_cleanup_ex, + &provider->rf TSRMLS_CC); + } + } else { + zend_hash_apply_with_argument(&provider->list.free, + php_persistent_handle_apply_cleanup, &provider->rf TSRMLS_CC); + } + + return ZEND_HASH_APPLY_KEEP; +} + +static void php_persistent_handle_hash_dtor(void *p) +{ + php_persistent_handle_provider_t *provider; + TSRMLS_FETCH(); + + provider = (php_persistent_handle_provider_t *) p; + zend_hash_apply_with_argument(&provider->list.free, + php_persistent_handle_list_apply_dtor, provider TSRMLS_CC); + zend_hash_destroy(&provider->list.free); + php_resource_factory_dtor(&provider->rf); +} + +PHP_RAPHF_API 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 *) TSRMLS_DC) +{ + ZEND_RESULT_CODE status = FAILURE; + php_persistent_handle_provider_t provider; + + if (php_persistent_handle_list_init(&provider.list)) { + if (php_resource_factory_init(&provider.rf, fops, data, dtor)) { +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "PROVIDE: %p %s\n", PHP_RAPHF_G, name_str); +#endif + + status = zend_symtable_update(&PHP_RAPHF_G->persistent_handle.hash, + name_str, name_len+1, (void *) &provider, + sizeof(php_persistent_handle_provider_t), NULL); + if (SUCCESS != status) { + php_resource_factory_dtor(&provider.rf); + } + } + } + + return status; +} + +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 TSRMLS_DC) +{ + ZEND_RESULT_CODE status = FAILURE; + php_persistent_handle_factory_t *free_a = NULL; + + if (!a) { + free_a = a = emalloc(sizeof(*a)); + } + memset(a, 0, sizeof(*a)); + + status = zend_symtable_find(&PHP_RAPHF_G->persistent_handle.hash, name_str, + name_len+1, (void *) &a->provider); + + if (SUCCESS == status) { + a->ident.str = estrndup(ident_str, ident_len); + a->ident.len = ident_len; + + a->wakeup = wakeup; + a->retire = retire; + + if (free_a) { + a->free_on_abandon = 1; + } + } else { + if (free_a) { + efree(free_a); + } + a = NULL; + } + +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "CONCEDE: %p %p (%s) (%s)\n", PHP_RAPHF_G, + a ? a->provider : NULL, name_str, ident_str); +#endif + + return a; +} + +PHP_RAPHF_API void php_persistent_handle_abandon( + php_persistent_handle_factory_t *a) +{ + zend_bool f = a->free_on_abandon; + +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "ABANDON: %p\n", a->provider); +#endif + + STR_FREE(a->ident.str); + memset(a, 0, sizeof(*a)); + if (f) { + efree(a); + } +} + +void *php_persistent_handle_acquire( + php_persistent_handle_factory_t *a, void *init_arg TSRMLS_DC) +{ + int key; + ZEND_RESULT_CODE rv; + ulong index; + void **handle_ptr, *handle = NULL; + php_persistent_handle_list_t *list; + + list = php_persistent_handle_list_find(a->provider, a->ident.str, + a->ident.len TSRMLS_CC); + if (list) { + zend_hash_internal_pointer_end(&list->free); + key = zend_hash_get_current_key(&list->free, NULL, &index, 0); + rv = zend_hash_get_current_data(&list->free, (void *) &handle_ptr); + if (HASH_KEY_NON_EXISTANT != key && SUCCESS == rv) { + handle = *handle_ptr; + if (a->wakeup) { + a->wakeup(a, &handle TSRMLS_CC); + } + zend_hash_index_del(&list->free, index); + } else { + handle = php_resource_factory_handle_ctor(&a->provider->rf, + init_arg TSRMLS_CC); + } +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "CREATED: %p\n", *handle); +#endif + if (handle) { + ++a->provider->list.used; + ++list->used; + } + } + + return handle; +} + +void *php_persistent_handle_accrete( + php_persistent_handle_factory_t *a, void *handle TSRMLS_DC) +{ + void *new_handle = NULL; + php_persistent_handle_list_t *list; + + new_handle = php_resource_factory_handle_copy(&a->provider->rf, + handle TSRMLS_CC); + if (handle) { + list = php_persistent_handle_list_find(a->provider, a->ident.str, + a->ident.len TSRMLS_CC); + if (list) { + ++list->used; + } + ++a->provider->list.used; + } + + return new_handle; +} + +void php_persistent_handle_release( + php_persistent_handle_factory_t *a, void *handle TSRMLS_DC) +{ + php_persistent_handle_list_t *list; + + list = php_persistent_handle_list_find(a->provider, a->ident.str, + a->ident.len TSRMLS_CC); + if (list) { + if (a->provider->list.used >= PHP_RAPHF_G->persistent_handle.limit) { +#if PHP_RAPHF_DEBUG_PHANDLES + fprintf(stderr, "DESTROY: %p\n", *handle); +#endif + php_resource_factory_handle_dtor(&a->provider->rf, + handle TSRMLS_CC); + } else { + if (a->retire) { + a->retire(a, &handle TSRMLS_CC); + } + zend_hash_next_index_insert(&list->free, (void *) &handle, + sizeof(void *), NULL); + } + + --a->provider->list.used; + --list->used; + } +} + +void php_persistent_handle_cleanup(const char *name_str, size_t name_len, + const char *ident_str, size_t ident_len TSRMLS_DC) +{ + php_persistent_handle_provider_t *provider; + php_persistent_handle_list_t *list; + ZEND_RESULT_CODE rv; + + if (name_str && name_len) { + rv = zend_symtable_find(&PHP_RAPHF_G->persistent_handle.hash, name_str, + name_len+1, (void *) &provider); + + if (SUCCESS == rv) { + if (ident_str && ident_len) { + list = php_persistent_handle_list_find(provider, ident_str, + ident_len TSRMLS_CC); + if (list) { + zend_hash_apply_with_argument(&list->free, + php_persistent_handle_apply_cleanup_ex, + &provider->rf TSRMLS_CC); + } + } else { + zend_hash_apply_with_argument(&provider->list.free, + php_persistent_handle_apply_cleanup, + &provider->rf TSRMLS_CC); + } + } + } else { + zend_hash_apply_with_arguments( + &PHP_RAPHF_G->persistent_handle.hash TSRMLS_CC, + php_persistent_handle_apply_cleanup_all, 2, ident_str, + ident_len); + } +} + +HashTable *php_persistent_handle_statall(HashTable *ht TSRMLS_DC) +{ + if (zend_hash_num_elements(&PHP_RAPHF_G->persistent_handle.hash)) { + if (!ht) { + ALLOC_HASHTABLE(ht); + zend_hash_init(ht, 0, NULL, ZVAL_PTR_DTOR, 0); + } + zend_hash_apply_with_arguments( + &PHP_RAPHF_G->persistent_handle.hash TSRMLS_CC, + php_persistent_handle_apply_statall, 1, ht); + } else if (ht) { + ht = NULL; + } + + return ht; +} + +static php_resource_factory_ops_t php_persistent_handle_resource_factory_ops = { + (php_resource_factory_handle_ctor_t) php_persistent_handle_acquire, + (php_resource_factory_handle_copy_t) php_persistent_handle_accrete, + (php_resource_factory_handle_dtor_t) php_persistent_handle_release +}; + +php_resource_factory_ops_t *php_persistent_handle_get_resource_factory_ops(void) +{ + return &php_persistent_handle_resource_factory_ops; +} + +ZEND_BEGIN_ARG_INFO_EX(ai_raphf_stat_persistent_handles, 0, 0, 0) +ZEND_END_ARG_INFO(); +static PHP_FUNCTION(raphf_stat_persistent_handles) +{ + if (SUCCESS == zend_parse_parameters_none()) { + object_init(return_value); + if (php_persistent_handle_statall(HASH_OF(return_value) TSRMLS_CC)) { + return; + } + zval_dtor(return_value); + } + RETURN_FALSE; +} + +ZEND_BEGIN_ARG_INFO_EX(ai_raphf_clean_persistent_handles, 0, 0, 0) + ZEND_ARG_INFO(0, name) + ZEND_ARG_INFO(0, ident) +ZEND_END_ARG_INFO(); +static PHP_FUNCTION(raphf_clean_persistent_handles) +{ + char *name_str = NULL, *ident_str = NULL; + int name_len = 0, ident_len = 0; + + if (SUCCESS == zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "|s!s!", + &name_str, &name_len, &ident_str, &ident_len)) { + php_persistent_handle_cleanup(name_str, name_len, ident_str, + ident_len TSRMLS_CC); + } +} + +static const zend_function_entry raphf_functions[] = { + ZEND_NS_FENTRY("raphf", stat_persistent_handles, + ZEND_FN(raphf_stat_persistent_handles), + ai_raphf_stat_persistent_handles, 0) + ZEND_NS_FENTRY("raphf", clean_persistent_handles, + ZEND_FN(raphf_clean_persistent_handles), + ai_raphf_clean_persistent_handles, 0) + {0} +}; + +PHP_INI_BEGIN() + STD_PHP_INI_ENTRY("raphf.persistent_handle.limit", "-1", PHP_INI_SYSTEM, + OnUpdateLong, persistent_handle.limit, zend_raphf_globals, + raphf_globals) +PHP_INI_END() + +static HashTable *php_persistent_handles_global_hash; + +static PHP_GINIT_FUNCTION(raphf) +{ + raphf_globals->persistent_handle.limit = -1; + + zend_hash_init(&raphf_globals->persistent_handle.hash, 0, NULL, + php_persistent_handle_hash_dtor, 1); + if (php_persistent_handles_global_hash) { + zend_hash_copy(&raphf_globals->persistent_handle.hash, + php_persistent_handles_global_hash, NULL, NULL, + sizeof(php_persistent_handle_provider_t)); + } +} + +static PHP_GSHUTDOWN_FUNCTION(raphf) +{ + zend_hash_destroy(&raphf_globals->persistent_handle.hash); +} + +PHP_MINIT_FUNCTION(raphf) +{ + php_persistent_handles_global_hash = &PHP_RAPHF_G->persistent_handle.hash; + REGISTER_INI_ENTRIES(); + return SUCCESS; +} + +PHP_MSHUTDOWN_FUNCTION(raphf) +{ + UNREGISTER_INI_ENTRIES(); + php_persistent_handles_global_hash = NULL; + return SUCCESS; +} + +static int php_persistent_handle_apply_info_ex(void *p TSRMLS_DC, int argc, + va_list argv, zend_hash_key *key) +{ + php_persistent_handle_list_t **list = p; + zend_hash_key *super_key = va_arg(argv, zend_hash_key *); + char used[21], free[21]; + + slprintf(used, sizeof(used), "%u", (*list)->used); + slprintf(free, sizeof(free), "%d", zend_hash_num_elements(&(*list)->free)); + + php_info_print_table_row(4, super_key->arKey, key->arKey, used, free); + + return ZEND_HASH_APPLY_KEEP; +} + +static int php_persistent_handle_apply_info(void *p TSRMLS_DC, int argc, + va_list argv, zend_hash_key *key) +{ + php_persistent_handle_provider_t *provider = p; + + zend_hash_apply_with_arguments(&provider->list.free TSRMLS_CC, + php_persistent_handle_apply_info_ex, 1, key); + + return ZEND_HASH_APPLY_KEEP; +} + +PHP_MINFO_FUNCTION(raphf) +{ + php_info_print_table_start(); + php_info_print_table_header(2, + "Resource and persistent handle factory support", "enabled"); + php_info_print_table_row(2, "Extension version", PHP_RAPHF_VERSION); + php_info_print_table_end(); + + php_info_print_table_start(); + php_info_print_table_colspan_header(4, "Persistent handles in this " +#ifdef ZTS + "thread" +#else + "process" +#endif + ); + php_info_print_table_header(4, "Provider", "Ident", "Used", "Free"); + zend_hash_apply_with_arguments( + &PHP_RAPHF_G->persistent_handle.hash TSRMLS_CC, + php_persistent_handle_apply_info, 0); + php_info_print_table_end(); + + DISPLAY_INI_ENTRIES(); +} + +zend_module_entry raphf_module_entry = { + STANDARD_MODULE_HEADER, + "raphf", + raphf_functions, + PHP_MINIT(raphf), + PHP_MSHUTDOWN(raphf), + NULL, + NULL, + PHP_MINFO(raphf), + PHP_RAPHF_VERSION, + ZEND_MODULE_GLOBALS(raphf), + PHP_GINIT(raphf), + PHP_GSHUTDOWN(raphf), + NULL, + STANDARD_MODULE_PROPERTIES_EX +}; +/* }}} */ + +#ifdef COMPILE_DL_RAPHF +ZEND_GET_MODULE(raphf) +#endif + + +/* + * Local variables: + * tab-width: 4 + * c-basic-offset: 4 + * End: + * vim600: noet sw=4 ts=4 fdm=marker + * vim<600: noet sw=4 ts=4 + */ diff --git a/src/php_raphf_api.h b/src/php_raphf_api.h new file mode 100644 index 0000000..4245c46 --- /dev/null +++ b/src/php_raphf_api.h @@ -0,0 +1,430 @@ +/* + +--------------------------------------------------------------------+ + | PECL :: raphf | + +--------------------------------------------------------------------+ + | Redistribution and use in source and binary forms, with or without | + | modification, are permitted provided that the conditions mentioned | + | in the accompanying LICENSE file are met. | + +--------------------------------------------------------------------+ + | Copyright (c) 2013, Michael Wallner | + +--------------------------------------------------------------------+ +*/ + +#ifndef PHP_RAPHF_API_H +#define PHP_RAPHF_API_H + +/** + * A resource constructor. + * + * @param opaque is the \a data from php_persistent_handle_provide() + * @param init_arg is the \a init_arg from php_resource_factory_init() + * @return the created (persistent) handle + */ +typedef void *(*php_resource_factory_handle_ctor_t)(void *opaque, + void *init_arg TSRMLS_DC); + +/** + * The copy constructor of a resource. + * + * @param opaque the factory's data + * @param handle the (persistent) handle to copy + */ +typedef void *(*php_resource_factory_handle_copy_t)(void *opaque, + void *handle TSRMLS_DC); + +/** + * The destructor of a resource. + * + * @param opaque the factory's data + * @param handle the handle to destroy + */ +typedef void (*php_resource_factory_handle_dtor_t)(void *opaque, + void *handle TSRMLS_DC); + +/** + * 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_ops { + /** The resource constructor */ + php_resource_factory_handle_ctor_t ctor; + /** The resource's copy constructor */ + php_resource_factory_handle_copy_t copy; + /** The resource's destructor */ + php_resource_factory_handle_dtor_t dtor; +} php_resource_factory_ops_t; + +/** + * The resource factory. + */ +typedef struct php_resource_factory { + /** The resource ops */ + php_resource_factory_ops_t fops; + /** Opaque user data */ + void *data; + /** User data destructor */ + void (*dtor)(void *data); + /** How often this factory is referenced */ + unsigned refcount; +} php_resource_factory_t; + +/** + * Initialize a resource factory. + * + * If you register a \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. + * + * @param f the factory to initialize; if NULL allocated on the heap + * @param fops the resource ops to assign to the factory + * @param data opaque user data; may be NULL + * @param dtor a destructor for the data; may be NULL + * @return \a f or an allocated resource factory + */ +PHP_RAPHF_API 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)); + +/** + * Increase the refcount of the resource factory. + * + * @param rf the resource factory + * @return the new refcount + */ +PHP_RAPHF_API unsigned php_resource_factory_addref(php_resource_factory_t *rf); + +/** + * Destroy the resource factory. + * + * If the factory's refcount reaches 0, the \a dtor for \a data is called. + * + * @param f the resource factory + */ +PHP_RAPHF_API void php_resource_factory_dtor(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. + * + * @param f the resource factory + */ +PHP_RAPHF_API void php_resource_factory_free(php_resource_factory_t **f); + +/** + * Construct a resource by the resource factory \a f + * + * @param f the resource factory + * @param init_arg for the resource constructor + * @return the new resource + */ +PHP_RAPHF_API void *php_resource_factory_handle_ctor(php_resource_factory_t *f, + void *init_arg TSRMLS_DC); + +/** + * Create a copy of the resource \a handle + * + * @param f the resource factory + * @param handle the resource to copy + * @return the copy + */ +PHP_RAPHF_API void *php_resource_factory_handle_copy(php_resource_factory_t *f, + void *handle TSRMLS_DC); + +/** + * Destroy (and free) the resource + * + * @param f the resource factory + * @param handle the resource to destroy + */ +PHP_RAPHF_API void php_resource_factory_handle_dtor(php_resource_factory_t *f, + void *handle TSRMLS_DC); + +/** + * Persistent handles storage + */ +typedef struct php_persistent_handle_list { + /** Storage of free resources */ + HashTable free; + /** Count of acquired resources */ + ulong used; +} php_persistent_handle_list_t; + +/** + * Definition of a persistent handle provider. + * Holds a resource factory an a persistent handle list. + */ +typedef struct php_persistent_handle_provider { + /** + * The list of free handles. + * Hash of "ident" => array(handles) entries. Persistent handles are + * acquired out of this list. + */ + php_persistent_handle_list_t list; + + /** + * The resource factory. + * New handles are created by this factory. + */ + php_resource_factory_t rf; +} php_persistent_handle_provider_t; + +typedef struct php_persistent_handle_factory php_persistent_handle_factory_t; + +/** + * Wakeup the persistent handle on re-acquisition. + */ +typedef void (*php_persistent_handle_wakeup_t)( + php_persistent_handle_factory_t *f, void **handle TSRMLS_DC); +/** + * Retire the persistent handle on release. + */ +typedef void (*php_persistent_handle_retire_t)( + php_persistent_handle_factory_t *f, void **handle TSRMLS_DC); + +/** + * 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 \a name_str has + * been registered with php_persistent_handle_provide(). + */ +struct php_persistent_handle_factory { + /** The persistent handle provider */ + php_persistent_handle_provider_t *provider; + /** The persistent handle wakeup routine; may be NULL */ + php_persistent_handle_wakeup_t wakeup; + /** The persistent handle retire routine; may be NULL */ + php_persistent_handle_retire_t retire; + + /** The ident for which this factory manages resources */ + struct { + /** ident string */ + char *str; + /** ident length */ + size_t len; + } ident; + + /** Whether it has to be free'd on php_persistent_handle_abandon() */ + unsigned free_on_abandon:1; +}; + +/** + * Register a persistent handle provider in MINIT. + * + * Registers a factory provider for \a name_str with \a fops resource factory + * ops. Call this in your MINIT. + * + * A php_resource_factory will be created with \a fops, \a data and \a 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. + * + * @param name_str the provider name, e.g. "http\Client\Curl" + * @param name_len the provider name length, e.g. strlen("http\Client\Curl") + * @param fops the resource factory ops + * @param data opaque user data + * @param dtor \a data destructor + * @return SUCCESS/FAILURE + */ +PHP_RAPHF_API int /* SUCCESS|FAILURE */ php_persistent_handle_provide( + const char *name_str, size_t name_len, php_resource_factory_ops_t *fops, + void *data, void (*dtor)(void *) TSRMLS_DC); + +/** + * Retrieve a persistent handle factory at runtime. + * + * If a persistent handle provider has been registered for \a name_str, a new + * php_persistent_handle_factory creating resources in the \a ident_str + * namespace will be constructed. + * + * The wakeup routine \a wakeup and the retire routine \a retire will be + * assigned to the new php_persistent_handle_factory. + * + * @param a pointer to a factory; allocated on the heap if NULL + * @param name_str the provider name, e.g. "http\Client\Curl" + * @param name_len the provider name length, e.g. strlen("http\Client\Curl") + * @param ident_str the subsidiary namespace, e.g. "php.net:80" + * @param ident_len the subsidiary namespace lenght, e.g. strlen("php.net:80") + * @param wakeup any persistent handle wakeup routine + * @param retire any persistent handle retire routine + * @return \a a or an allocated persistent handle factory + */ +PHP_RAPHF_API 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 TSRMLS_DC); + +/** + * 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. + * + * @param a the persistent handle factory to destroy + */ +PHP_RAPHF_API void php_persistent_handle_abandon( + php_persistent_handle_factory_t *a); + +/** + * 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. + * + * @param a the persistent handle factory + * @param init_arg the \a init_arg for php_resource_factory_handle_ctor() + * @return the acquired resource + */ +PHP_RAPHF_API void *php_persistent_handle_acquire( + php_persistent_handle_factory_t *a, void *init_arg TSRMLS_DC); + +/** + * 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. + * + * @param a the persistent handle factory + * @param handle the handle to release + */ +PHP_RAPHF_API void php_persistent_handle_release( + php_persistent_handle_factory_t *a, void *handle TSRMLS_DC); + +/** + * Copy a persistent handle. + * + * Let the underlying resource factory copy the \a handle. + * + * @param a the persistent handle factory + * @param handle the resource to accrete + */ +PHP_RAPHF_API void *php_persistent_handle_accrete( + php_persistent_handle_factory_t *a, void *handle TSRMLS_DC); + +/** + * 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: + * ~~~~~~~~~~~~~~~{.c} + * 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; + * } + * ~~~~~~~~~~~~~~~ + */ +PHP_RAPHF_API php_resource_factory_ops_t * +php_persistent_handle_get_resource_factory_ops(void); + +/** + * Create a resource factory for persistent handles. + * + * This will create a resource factory with persistent handle ops, which wraps + * the provided reource factory \a pf. + * + * @param a the persistent handle resource factory to initialize + * @param pf the resource factory to wrap + */ +PHP_RAPHF_API php_resource_factory_t * +php_persistent_handle_resource_factory_init(php_resource_factory_t *a, + php_persistent_handle_factory_t *pf); + +/** + * Check whether a resource factory is a persistent handle resource factory. + * + * @param a the resource factory to check + */ +PHP_RAPHF_API zend_bool php_resource_factory_is_persistent( + php_resource_factory_t *a); + +/** + * Clean persistent handles up. + * + * Destroy persistent handles of provider \a name_str and in subsidiary + * namespace \a ident_str. + * + * If \a name_str is NULL, all persistent handles of all providers with a + * matching \a ident_str will be cleaned up. + * + * If \a ident_str is NULL all persistent handles of the provider will be + * cleaned up. + * + * Ergo, if both, \a name_str and \a 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. + * + * @param name_str the provider name; may be NULL + * @param name_len the provider name length + * @param ident_str the subsidiary namespace name; may be NULL + * @param ident_len the subsidiary namespace name length + */ +PHP_RAPHF_API void php_persistent_handle_cleanup(const char *name_str, + size_t name_len, const char *ident_str, size_t ident_len TSRMLS_DC); + +/** + * Retrieve statistics about the current process/thread's persistent handles. + * + * @return a HashTable like: + * ~~~~~~~~~~~~~~~ + * [ + * "name" => [ + * "ident" => [ + * "used" => 1, + * "free" => 0, + * ] + * ] + * ] + * ~~~~~~~~~~~~~~~ + */ +PHP_RAPHF_API HashTable *php_persistent_handle_statall(HashTable *ht TSRMLS_DC); + +#endif /* PHP_RAPHF_API_H */ + + +/* + * Local variables: + * tab-width: 4 + * c-basic-offset: 4 + * End: + * vim600: noet sw=4 ts=4 fdm=marker + * vim<600: noet sw=4 ts=4 + */