sapi_module_struct 研究(一)

今日研究了PHP中的sapi_module_struct结构体。众所周知，PHP_CLI中先include了SAPI.h。先列出这个著名的stuct。 琢磨虽一无是用，但人生本有何用？

struct _sapi_module_struct {
	char *name;
	char *pretty_name;

	int (*startup)(struct _sapi_module_struct *sapi_module);
	int (*shutdown)(struct _sapi_module_struct *sapi_module);

	int (*activate)(TSRMLS_D);
	int (*deactivate)(TSRMLS_D);

	int (*ub_write)(const char *str, unsigned int str_length TSRMLS_DC);
	void (*flush)(void *server_context);
	struct stat *(*get_stat)(TSRMLS_D);
	char *(*getenv)(char *name, size_t name_len TSRMLS_DC);

	void (*sapi_error)(int type, const char *error_msg, ...);

	int (*header_handler)(sapi_header_struct *sapi_header, sapi_header_op_enum op, sapi_headers_struct *sapi_headers TSRMLS_DC);
	int (*send_headers)(sapi_headers_struct *sapi_headers TSRMLS_DC);
	void (*send_header)(sapi_header_struct *sapi_header, void *server_context TSRMLS_DC);

	int (*read_post)(char *buffer, uint count_bytes TSRMLS_DC);
	char *(*read_cookies)(TSRMLS_D);

	void (*register_server_variables)(zval *track_vars_array TSRMLS_DC);
	void (*log_message)(char *message TSRMLS_DC);
	double (*get_request_time)(TSRMLS_D);
	void (*terminate_process)(TSRMLS_D);

	char *php_ini_path_override;

	void (*block_interruptions)(void);
	void (*unblock_interruptions)(void);

	void (*default_post_reader)(TSRMLS_D);
	void (*treat_data)(int arg, char *str, zval *destArray TSRMLS_DC);
	char *executable_location;

	int php_ini_ignore;
	int php_ini_ignore_cwd; /* don't look for php.ini in the current directory */

	int (*get_fd)(int *fd TSRMLS_DC);

	int (*force_http_10)(TSRMLS_D);

	int (*get_target_uid)(uid_t * TSRMLS_DC);
	int (*get_target_gid)(gid_t * TSRMLS_DC);

	unsigned int (*input_filter)(int arg, char *var, char **val, unsigned int val_len, unsigned int *new_val_len TSRMLS_DC);
	
	void (*ini_defaults)(HashTable *configuration_hash);
	int phpinfo_as_text;

	char *ini_entries;
	const zend_function_entry *additional_functions;
	unsigned int (*input_filter_init)(TSRMLS_D);
};

上面结构体给出了sapi_module_struct定义。在CLI作为SAPI入口的内核的启动过程中，至少创建了这样的一个实例：

static sapi_module_struct cli_sapi_module = {
	"cli",							/* name */
	"Command Line Interface",    	/* pretty name */

	php_cli_startup,				/* startup */
	php_module_shutdown_wrapper,	/* shutdown */

	NULL,							/* activate */
	sapi_cli_deactivate,			/* deactivate */

	sapi_cli_ub_write,		    	/* unbuffered write */
	sapi_cli_flush,				    /* flush */
	NULL,							/* get uid */
	NULL,							/* getenv */

	php_error,						/* error handler */

	sapi_cli_header_handler,		/* header handler */
	sapi_cli_send_headers,			/* send headers handler */
	sapi_cli_send_header,			/* send header handler */

	NULL,				            /* read POST data */
	sapi_cli_read_cookies,          /* read Cookies */

	sapi_cli_register_variables,	/* register server variables */
	sapi_cli_log_message,			/* Log message */
	NULL,							/* Get request time */
	NULL,							/* Child terminate */
	
	STANDARD_SAPI_MODULE_PROPERTIES
};

这个cli_sapi_module在main函数中将地址交给了sapi_module指针变量：

	sapi_module_struct *sapi_module = &cli_sapi_module;

因而，在CLI主函数内，这个sapi_module指针被送入php_module_startup等上层进行启动。在这里进入了启动过程：

if (sapi_module->startup(sapi_module) == FAILURE) {
		/* there is no way to see if we must call zend_ini_deactivate()
		 * since we cannot check if EG(ini_directives) has been initialised
		 * because the executor's constructor does not set initialize it.
		 * Apart from that there seems no need for zend_ini_deactivate() yet.
		 * So we goto out_err.*/
		exit_status = 1;
		goto out;
	}

由于是指针，访问成员函数使用了 "->"。

然而在PHP_API/ZEND_API中，均使用了sapi_module.ub_write()访问成员函数，在命名中为什么要使用相同的变量名呢？容易搞晕。如下例：

/* {{{ int php_output_write_unbuffered(const char *str, size_t len TSRMLS_DC)
 * Unbuffered write */
PHPAPI int php_output_write_unbuffered(const char *str, size_t len TSRMLS_DC)
{
#if PHP_DEBUG
	if (len > UINT_MAX) {
		php_error(E_WARNING, "Attempt to output more than UINT_MAX bytes at once; "
				"output will be truncated %lu => %lu",
				(unsigned long) len, (unsigned long) (len % UINT_MAX));
	}
#endif
	if (OG(flags) & PHP_OUTPUT_DISABLED) {
		return 0;
	}
	if (OG(flags) & PHP_OUTPUT_ACTIVATED) {
		return sapi_module.ub_write(str, len TSRMLS_CC);
	}
	return php_output_direct(str, len);
}

这是因为，在SAPI.C文件中，定义了sapi_module这样一个全局变量：

/* True globals (no need for thread safety) */
SAPI_API sapi_module_struct sapi_module;

这个变量在SAPI.h中被extern:

BEGIN_EXTERN_C()
extern SAPI_API sapi_module_struct <strong>sapi_module</strong>;  /* true global */
END_EXTERN_C()

定义说明它不是指针类型，它在何处拥有了cli_sapi_module的成员呢？我猜估计在php_module_startup里，果然是：

/* {{{ php_module_startup
 */
int php_module_startup(sapi_module_struct *sf, zend_module_entry *additional_modules, uint num_additional_modules)
{
	zend_utility_functions zuf;
	zend_utility_values zuv;
	int retval = SUCCESS, module_number=0;	/* for REGISTER_INI_ENTRIES() */
	char *php_os;
	zend_module_entry *module;
#ifdef ZTS
	zend_executor_globals *executor_globals;
	void ***tsrm_ls;
	php_core_globals *core_globals;
#endif

#if defined(PHP_WIN32) || (defined(NETWARE) && defined(USE_WINSOCK))
	WORD wVersionRequested = MAKEWORD(2, 0);
	WSADATA wsaData;
#endif
#ifdef PHP_WIN32
	php_os = "WINNT";
#if _MSC_VER >= 1400
	old_invalid_parameter_handler =
		_set_invalid_parameter_handler(dummy_invalid_parameter_handler);
	if (old_invalid_parameter_handler != NULL) {
		_set_invalid_parameter_handler(old_invalid_parameter_handler);
	}

	/* Disable the message box for assertions.*/
	_CrtSetReportMode(_CRT_ASSERT, 0);
#endif
#else
	php_os=PHP_OS;
#endif

#ifdef ZTS
	tsrm_ls = ts_resource(0);
#endif

#ifdef PHP_WIN32
	php_win32_init_rng_lock();
#endif

	module_shutdown = 0;
	module_startup = 1;
	sapi_initialize_empty_request(TSRMLS_C);
	sapi_activate(TSRMLS_C);

	if (module_initialized) {
		return SUCCESS;
	}

	sapi_module = *sf;

	php_output_startup();
        // ......//
}

自此以后，只要include "sapi.h"即可访问SAPI定义的函数。通过这种设计，成功的将不同SAPI的sapi_module送给同一个上层全局变量。使得上层handler不用关心底层的具体实现。