Differences

This shows you the differences between two versions of the page.

--- internals:engine [2010/04/25 20:11] – derick
+++ internals:engine [2010/04/28 12:21] – added extension globals cataphract
@@ Line 51: / Line 51: @@
 Add your random stuff here. I'll move it/update it/fix it (Derick)
+==== Extension Globals =====
+To use extension globals (which are either true globals or thread local globals, depending on whether ZTS is enabled), follow these steps:
+- In php_extname.h, declare which global variables you need with:
+<code>
+ZEND_BEGIN_MODULE_GLOBALS(extname)
+	int	var1;
+	char	*var2;
+	....
+ZEND_END_MODULE_GLOBALS(extname)
+</code>
+This will declare a structure (typedef'd to zend_extname_globals) that will hold all your globals.
+- In php_extname.h, add <code>ZEND_EXTERN_MODULE_GLOBALS(extname);</code>. This will produce an allusion that will allow you to access the globals from every compile unit that includes php_extname.h In particular, this produces an allusion to an integer named extname_globals_id in ZTS builds or directly to a zend_extname_globals named extname_globals in non-ZTS builds.
+- In php_extname.h, define a macro named EXTNAME_G, like this:
+<code>
+#ifdef ZTS
+# define EXTNAME_G(v) TSRMG(extname_globals_id, zend_extname_globals *, v)
+#else
+# define EXTNAME_G(v) (extname_globals.v)
+#endif
+</code>
+This will allow you to access the globals in a consistent manner in both ZTS and non-ZTS builds, like this:
+<code>EXTNAME_G(var1)</code>
+- Now that you have declared the type that aggregates the globals and the variable that holds the globals, you must define the globals. In extname.c, add
+<code>ZEND_DECLARE_MODULE_GLOBALS(extname);</code>
+This produces a tentative definition of extname_globals_id or extname_globals (depending on whether it's a ZTS or non-ZTS build).
+- If you needn't do any startup operations on your variables, you would already have function extension globals in non-ZTS builds. Tipically, you will also want to initialize some extension globals (for instance, to allocate some memory for the var2 extension global above) -- this is done with globals constructors and destructors. To make it work in ZTS builds and allow such operations, add the following to your zend_module_entry:
+<code>
+zend_module_entry extname_module_entry = {
+	...
+	ZEND_MODULE_INFO_N(extname),
+	PHP_EXTNAME_VERSION,
+	ZEND_MODULE_GLOBALS(extname),
+	ZEND_MODULE_GLOBALS_CTOR_N(extname), //may be NULL
+	ZEND_MODULE_GLOBALS_DTOR_N(extname), //may be NULL
+	...
+}
+</code>
+Note: do not use ZEND_INIT_MODULE_GLOBALS/ts_allocate_id. If used a shared extension, they will provoke an attempt to call the destructor after the module has been unloaded!
+- Now define the constructor and destructor functions:
+<code>
+ZEND_MODULE_GLOBALS_CTOR_D(extname)
+{
+	extname_globals->arg2 = pemalloc(1024, 1);
+}
+ZEND_MODULE_GLOBALS_DTOR_D(extname)
+{
+	pefree(extname_globals->arg2, 1);
+}
+</code>
+Note: ZEND_MODULE_GLOBALS_CTOR_D will declare a function as receiving a zend_extname_globals*, not void* and zend_module_entry is supposed to contain a function pointer type that receives void*. I think this violates the C standard (the declarations are incompatible), but should however by safe since the arguments have the same size.

Differences

Page Tools