JFC, fix the merge here, too
authorMichael Wallner <mike@php.net>
Mon, 28 Sep 2015 15:53:59 +0000 (17:53 +0200)
committerMichael Wallner <mike@php.net>
Mon, 28 Sep 2015 16:03:13 +0000 (18:03 +0200)
php_raphf_api.h

index 4245c468efbf6b284988b0c6c5d453b626b2f6a0..f5abb82ed0147a6f04a8a4f4e1638d5248ef78b5 100644 (file)
@@ -13,6 +13,8 @@
 #ifndef PHP_RAPHF_API_H
 #define PHP_RAPHF_API_H
 
+#include "php_raphf.h"
+
 /**
  * A resource constructor.
  *
@@ -20,8 +22,7 @@
  * @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);
+typedef void *(*php_resource_factory_handle_ctor_t)(void *opaque, void *init_arg);
 
 /**
  * The copy constructor of a resource.
@@ -29,8 +30,7 @@ typedef void *(*php_resource_factory_handle_ctor_t)(void *opaque,
  * @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);
+typedef void *(*php_resource_factory_handle_copy_t)(void *opaque, void *handle);
 
 /**
  * The destructor of a resource.
@@ -38,8 +38,7 @@ typedef void *(*php_resource_factory_handle_copy_t)(void *opaque,
  * @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);
+typedef void (*php_resource_factory_handle_dtor_t)(void *opaque, void *handle);
 
 /**
  * The resource ops consisting of a ctor, a copy ctor and a dtor.
@@ -108,7 +107,7 @@ 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
+ * Calls php_resource_factory_dtor() and frees \a f if the factory's refcount
  * reached 0.
  *
  * @param f the resource factory
@@ -123,7 +122,7 @@ PHP_RAPHF_API void php_resource_factory_free(php_resource_factory_t **f);
  * @return the new resource
  */
 PHP_RAPHF_API void *php_resource_factory_handle_ctor(php_resource_factory_t *f,
-               void *init_arg TSRMLS_DC);
+               void *init_arg);
 
 /**
  * Create a copy of the resource \a handle
@@ -133,7 +132,7 @@ PHP_RAPHF_API void *php_resource_factory_handle_ctor(php_resource_factory_t *f,
  * @return the copy
  */
 PHP_RAPHF_API void *php_resource_factory_handle_copy(php_resource_factory_t *f,
-               void *handle TSRMLS_DC);
+               void *handle);
 
 /**
  * Destroy (and free) the resource
@@ -142,7 +141,7 @@ PHP_RAPHF_API void *php_resource_factory_handle_copy(php_resource_factory_t *f,
  * @param handle the resource to destroy
  */
 PHP_RAPHF_API void php_resource_factory_handle_dtor(php_resource_factory_t *f,
-               void *handle TSRMLS_DC);
+               void *handle);
 
 /**
  * Persistent handles storage
@@ -179,18 +178,18 @@ 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);
+               php_persistent_handle_factory_t *f, void **handle);
 /**
  * Retire the persistent handle on release.
  */
 typedef void (*php_persistent_handle_retire_t)(
-               php_persistent_handle_factory_t *f, void **handle TSRMLS_DC);
+               php_persistent_handle_factory_t *f, void **handle);
 
 /**
  * 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
+ * php_persistent_handle_factory if a provider for the \a name has
  * been registered with php_persistent_handle_provide().
  */
 struct php_persistent_handle_factory {
@@ -202,12 +201,7 @@ struct php_persistent_handle_factory {
        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;
+       zend_string *ident;
 
        /** Whether it has to be free'd on php_persistent_handle_abandon() */
        unsigned free_on_abandon:1;
@@ -226,41 +220,38 @@ struct php_persistent_handle_factory {
  * 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 name the provider name, e.g. "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);
+PHP_RAPHF_API ZEND_RESULT_CODE php_persistent_handle_provide(
+               zend_string *name, php_resource_factory_ops_t *fops,
+               void *data, void (*dtor)(void *));
 
 /**
  * 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
+ * If a persistent handle provider has been registered for \a name, a new
+ * php_persistent_handle_factory creating resources in the \a ident
  * 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 name the provider name, e.g. "http\Client\Curl"
+ * @param ident the subsidiary namespace, e.g. "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_factory_t *a,
+               zend_string *name, zend_string *ident,
                php_persistent_handle_wakeup_t wakeup,
-               php_persistent_handle_retire_t retire TSRMLS_DC);
+               php_persistent_handle_retire_t retire);
 
 /**
  * Abandon the persistent handle factory.
@@ -288,7 +279,7 @@ PHP_RAPHF_API void php_persistent_handle_abandon(
  * @return the acquired resource
  */
 PHP_RAPHF_API void *php_persistent_handle_acquire(
-               php_persistent_handle_factory_t *a, void *init_arg TSRMLS_DC);
+               php_persistent_handle_factory_t *a, void *init_arg);
 
 /**
  * Release a persistent handle.
@@ -304,7 +295,7 @@ PHP_RAPHF_API void *php_persistent_handle_acquire(
  * @param handle the handle to release
  */
 PHP_RAPHF_API void php_persistent_handle_release(
-               php_persistent_handle_factory_t *a, void *handle TSRMLS_DC);
+               php_persistent_handle_factory_t *a, void *handle);
 
 /**
  * Copy a persistent handle.
@@ -315,7 +306,7 @@ PHP_RAPHF_API void php_persistent_handle_release(
  * @param handle the resource to accrete
  */
 PHP_RAPHF_API void *php_persistent_handle_accrete(
-               php_persistent_handle_factory_t *a, void *handle TSRMLS_DC);
+               php_persistent_handle_factory_t *a, void *handle);
 
 /**
  * Retrieve persistent handle resource factory ops.
@@ -327,21 +318,19 @@ PHP_RAPHF_API void *php_persistent_handle_accrete(
  *
  * 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 *create_my_rf(zend_string *persistent_id)
  * {
  *     php_resource_factory_t *rf;
  *
- *     if (persistent_id_str) {
+ *     if (persistent_id) {
  *         php_persistent_handle_factory_t *pf;
  *         php_resource_factory_ops_t *ops;
+ *         zend_string *ns = zend_string_init("my", 2, 1);
  *
  *         ops = php_persistent_handle_get_resource_factory_ops();
- *
- *         pf = php_persistent_handle_concede(NULL, "my", 2,
- *             persistent_id_str, persistent_id_len, NULL, NULL TSRMLS_CC);
- *
+ *         pf = php_persistent_handle_concede(NULL, ns, persistent_id, NULL, NULL);
  *         rf = php_persistent_handle_resource_factory_init(NULL, pf);
+ *         zend_string_release(ns);
  *     } else {
  *         rf = php_resource_factory_init(NULL, &myops, NULL, NULL);
  *     }
@@ -376,29 +365,27 @@ PHP_RAPHF_API zend_bool php_resource_factory_is_persistent(
 /**
  * Clean persistent handles up.
  *
- * Destroy persistent handles of provider \a name_str and in subsidiary
- * namespace \a ident_str.
+ * Destroy persistent handles of provider \a name and in subsidiary
+ * namespace \a ident.
  *
- * If \a name_str is NULL, all persistent handles of all providers with a
- * matching \a ident_str will be cleaned up.
+ * If \a name is NULL, all persistent handles of all providers with a
+ * matching \a ident will be cleaned up.
  *
- * If \a ident_str is NULL all persistent handles of the provider will be
+ * If \a identr 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
+ * Ergo, if both, \a name and \a ident are NULL, then all
  * persistent handles will be cleaned up.
  *
  * You must call this in MSHUTDOWN, if your resource factory ops hold a
  * registered php_resource_factory::dtor, else the dtor will point to
  * memory not any more available if the extension has already been unloaded.
  *
- * @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
+ * @param name the provider name; may be NULL
+ * @param ident the subsidiary namespace name; may be NULL
  */
-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);
+PHP_RAPHF_API void php_persistent_handle_cleanup(zend_string *name,
+               zend_string *ident);
 
 /**
  * Retrieve statistics about the current process/thread's persistent handles.
@@ -415,7 +402,7 @@ PHP_RAPHF_API void php_persistent_handle_cleanup(const char *name_str,
  *     ]
  * ~~~~~~~~~~~~~~~
  */
-PHP_RAPHF_API HashTable *php_persistent_handle_statall(HashTable *ht TSRMLS_DC);
+PHP_RAPHF_API HashTable *php_persistent_handle_statall(HashTable *ht);
 
 #endif /* PHP_RAPHF_API_H */