完善代码注释

jilieryuyi · Oct 10, 2017 · d2ff1f0 · d2ff1f0
1 parent 167b886
commit d2ff1f0
Show file tree

Hide file tree

Showing 4 changed files with 119 additions and 37 deletions.
diff --git a/linux/linux_api.c b/linux/linux_api.c
@@ -3,6 +3,12 @@ extern char* PHP_PATH;
 /**
  * linux或者mac查找命令所在路径，使用完需要free释放资源
  * 如：get_command_path("php"); //返回 /usr/bin/php
+ *
+ * @param const char* command 需要查询的命令
+ * @return char* 堆内存，需要手动free，如：
+ *    char *path =  wing_get_command_path("php");
+ *    ...//其他操作
+ *    free(path);
  */
 char* wing_get_command_path(const char* command)
 {
@@ -58,7 +64,11 @@ char* wing_get_command_path(const char* command)
     return NULL;
 }
 
-
+/**
+ * 启用守护进程模式
+ *
+ * @param const char* dir 工作目录
+ */
 void init_daemon(const char* dir)
 {
     int pid = fork();
@@ -89,6 +99,13 @@ void init_daemon(const char* dir)
     return;
 }
 
+/**
+ * 创建一个新的进程
+ *
+ * @param const char *command 需要以守护进程运行的指令
+ * @param char* output_file 输出重定向到文件，如果不等于NULL，则认为是以守护方式运行
+ * @return unsigned long 进程id
+ */
 unsigned long wing_create_process(const char *command, char* output_file)
 {
     TSRMLS_FETCH();
@@ -268,6 +285,11 @@ unsigned long wing_create_process(const char *command, char* output_file)
     return (unsigned long )childpid;
 }
 
+/**
+ * 获取当前进程id
+ *
+ * @return pid_t （int）
+ */
 int wing_get_process_id()
 {
     return getpid();
@@ -276,6 +298,9 @@ int wing_get_process_id()
 #ifdef __APPLE__
 /**
  * mac下面获取进程占用内存 返回单位为k
+ *
+ * @param int process_id 进程id
+ * @return int
  */
 unsigned long wing_get_memory(int process_id)
 {
@@ -291,6 +316,9 @@ unsigned long wing_get_memory(int process_id)
 #else
 /**
  * linux下面获取进程占用内存 返回单位为k
+ *
+ * @param int process_id 进程id
+ * @return int
  */
 unsigned long wing_get_memory(int process_id)
 {

diff --git a/wing_api.c b/wing_api.c
@@ -1,4 +1,6 @@
-
+/**
+ * 读取类的属性，这里为了兼容php7和其他版本所做的简单的条件编译封装
+ */
 zval *wing_zend_read_property(zend_class_entry *scope, zval *object, const char *name)
 {
 	TSRMLS_FETCH();
@@ -11,11 +13,11 @@ zval *wing_zend_read_property(zend_class_entry *scope, zval *object, const char
 
 
 /**
-* ?��?????php??????????????php???????? <?php ???
-*
-* @param char* file
-* @return BOOL
-*/
+ * 判断文件是否为php文件
+ *
+ * @param const char* file
+ * @return BOOL
+ */
 int wing_file_is_php(const char *file)
 {
     char path[MAX_PATH] = {0};
@@ -91,10 +93,6 @@ int wing_file_is_php(const char *file)
     return 0;
 }
 
-
-
-
-
 //int wing_write_cmdline(unsigned long process_id, char *cmdline)
 //{
 //    char buffer[MAX_PATH];
@@ -133,14 +131,18 @@ int wing_file_is_php(const char *file)
     return 0;*/
 //}
 #ifdef __APPLE__
-
-void wing_get_cmdline(int pid, char **buffer) {
+/**
+ * mac下面获取进程的启动命令
+ *
+ * @param int pid 进程id
+ * @param char **buffer 输出结果到buffer
+ */
+void wing_get_cmdline(int pid, char **buffer)
+{
     int    mib[3], argmax, nargs, c = 0;
-    size_t    size;
-    char    *procargs, *sp, *np, *cp;
-    int show_args = 1;
-
-    //fprintf(stderr, "Getting argv of PID %d\n", pid);
+    size_t size;
+    char   *procargs, *sp, *np, *cp;
+    int    show_args = 1;
 
     mib[0] = CTL_KERN;
     mib[1] = KERN_ARGMAX;
@@ -156,7 +158,6 @@ void wing_get_cmdline(int pid, char **buffer) {
         goto ERROR_A;
     }
 
-
     /*
      * Make a sysctl() call to get the raw argument space of the process.
      * The layout is documented in start.s, which is part of the Csu
@@ -295,8 +296,14 @@ void wing_get_cmdline(int pid, char **buffer) {
     //exit(2);
 }
 
-
 #else
+/**
+ * linux下获取进程的启动命令（进程名称），这里获取到的命令可能不准确
+ * 如果被set_process_title重命名过的进程无法正常获取，只会返回
+ *
+ * @param int pid 进程id
+ * @param char **buffer 输出结果到buffer
+ */
 void wing_get_cmdline(int process_id, char **buffer)
 {
     *buffer = NULL;

diff --git a/wing_api.h b/wing_api.h
@@ -28,10 +28,31 @@ unsigned long wing_get_memory(int process_id);
 int wing_kill(int process_id);
 zval *wing_zend_read_property(zend_class_entry *scope, zval *object, const char *name);
 void wing_get_tmp_dir(char *buffer);
-//int wing_write_cmdline(unsigned long process_id, char *cmdline);
 void wing_get_cmdline(int process_id, char **buffer);
 
-int wing_access(const char* file, int mode) {
+/**
+ * 判断文件是否存在、是否可读、可写等等
+ * @param const char* file 文件路径
+ * @param int mode 可直接使用系统定义的常量，可以组合使用，比如判断是否可读并且可写，传入 R_OK|W_OK
+     在头文件unistd.h中的预定义如下：
+     #define R_OK 4
+     #define W_OK 2
+     #define X_OK 1
+     #define F_OK 0
+     具体含义如下：
+     R_OK 只判断是否有读权限
+     W_OK 只判断是否有写权限
+     X_OK 判断是否有执行权限
+     F_OK 只判断是否存在
+     在宏定义里面分别对应：
+     00 只存在
+     02 写权限
+     04 读权限
+     06 读和写权限
+ * @return int 0代表成功 -1代表失败，使用的时候判断 == 0 或者 == -1 、!= 0 即可
+ */
+int wing_access(const char* file, int mode)
+{
 #ifdef PHP_WIN32
 	return _access(file, mode);
 #else 

diff --git a/wing_process.c b/wing_process.c
@@ -48,7 +48,6 @@ typedef struct _WING_PROCESS_INFO {
 
 /**
  * 构造函数，第一个参数为需要以守护进程执行的php文件或者是其他可执行的命令和文件
- * 第二个参数为重定向输出的文件路径
  * 如果传入的文件是一个数字，则认为根据进程id打开进程，后续可以对此进程进行控制，比如kill
  *
  * @param string $file
@@ -212,7 +211,7 @@ ZEND_METHOD(wing_process, __destruct) {
  */
 ZEND_METHOD(wing_process, run)
 {
-   char *output_file = NULL;
+    char *output_file = NULL;
 
     #if PHP_MAJOR_VERSION >= 7
 
@@ -252,8 +251,8 @@ ZEND_METHOD(wing_process, run)
  * @param int $timout windows下面的意思为等待超时时间，linux下面的意思为是否等待，可选参数如 WNOHANG | WUNTRACED
  * @return int
  */
-ZEND_METHOD(wing_process, wait) {
-
+ZEND_METHOD(wing_process, wait)
+{
 	int timeout = INFINITE;
 	zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "|l", &timeout);
 
@@ -295,7 +294,8 @@ ZEND_METHOD(wing_process, wait) {
  *
  * @return int
  */
-ZEND_METHOD(wing_process, getProcessId) {
+ZEND_METHOD(wing_process, getProcessId)
+{
 	zval *_info = wing_zend_read_property(wing_process_ce, getThis(),"process_info");
     WING_PROCESS_INFO *info = (WING_PROCESS_INFO *)Z_LVAL_P(_info);
     RETURN_LONG(info->process_id);
@@ -307,7 +307,8 @@ ZEND_METHOD(wing_process, getProcessId) {
  *
  * @return int
  */
-ZEND_METHOD(wing_process, getThreadId) {
+ZEND_METHOD(wing_process, getThreadId)
+{
     zval *_info = wing_zend_read_property(wing_process_ce, getThis(),"process_info");
     WING_PROCESS_INFO *info = (WING_PROCESS_INFO *)Z_LVAL_P(_info);
     #ifdef PHP_WIN32
@@ -354,6 +355,7 @@ ZEND_METHOD(wing_process, kill)
 		PROCESS_INFORMATION *pi = (PROCESS_INFORMATION *)(info->ext_info);
 		process   = pi->hProcess;
 	}
+
     //非安全的方式直接退出 可能造成进程数据丢失
 	if (!TerminateProcess(process, 0)) {
 		RETURN_FALSE;//LONG(WING_ERROR_FAILED);
@@ -363,29 +365,36 @@ ZEND_METHOD(wing_process, kill)
 	RETURN_TRUE;
 	#else
     int process_id = 0;
+
     if (is_numeric_string(info->file, strlen(info->file), NULL, NULL, 0)) {
         process_id = zend_atoi(info->file, strlen(info->file));
     } else {
         process_id = info->process_id;
     }
+
     int status = kill(process_id, SIGKILL);
+
     if (status == -1) {
         RETURN_FALSE;
     }
+
     wait(&status);
+
     if (WIFSIGNALED(status)) {
         RETURN_TRUE;
     }
+
     RETURN_FALSE;
 	#endif
 }
 
 /**
- * 返回进程占用的实际内存，单位为字节
+ * 返回进程占用的实际内存，单位为k
  *
  * @return int
  */
-ZEND_METHOD(wing_process, getMemory) {
+ZEND_METHOD(wing_process, getMemory)
+{
 	zval *_info = wing_zend_read_property(wing_process_ce, getThis(),"process_info");
     WING_PROCESS_INFO *info = (WING_PROCESS_INFO *)Z_LVAL_P(_info);
 
@@ -414,15 +423,17 @@ ZEND_METHOD(wing_process, getMemory) {
 
 /**
  * 静态方法，获取当前进程id
- *
+ * @call \wing\wing_process::getCurrentProcessId()
  * @return int
  */
-ZEND_METHOD(wing_process, getCurrentProcessId) {
+ZEND_METHOD(wing_process, getCurrentProcessId)
+{
 	ZVAL_LONG(return_value, wing_get_process_id());
 }
 
 
-static zend_function_entry wing_process_methods[] = {
+static zend_function_entry wing_process_methods[] =
+{
 	ZEND_ME(wing_process, __construct, NULL,ZEND_ACC_PUBLIC | ZEND_ACC_CTOR)
 	ZEND_ME(wing_process, __destruct, NULL,ZEND_ACC_PUBLIC | ZEND_ACC_DTOR)
 	ZEND_ME(wing_process, wait, NULL,ZEND_ACC_PUBLIC)
@@ -438,7 +449,9 @@ static zend_function_entry wing_process_methods[] = {
 	}
 };
 
-
+/**
+ * 模块初始化，这里会初始化PHP_PATH，也就是php的可执行文件路径
+ */
 PHP_MINIT_FUNCTION(wing_process)
 {
 
@@ -455,6 +468,9 @@ PHP_MINIT_FUNCTION(wing_process)
 	return SUCCESS;
 }
 
+/**
+ * 模块释放
+ */
 PHP_MSHUTDOWN_FUNCTION(wing_process)
 {
 	if (PHP_PATH) {
@@ -463,6 +479,9 @@ PHP_MSHUTDOWN_FUNCTION(wing_process)
 	return SUCCESS;
 }
 
+/**
+ * 模块请求初始化
+ */
 PHP_RINIT_FUNCTION(wing_process)
 {
 #if PHP_MAJOR_VERSION >= 7
@@ -473,11 +492,17 @@ PHP_RINIT_FUNCTION(wing_process)
 	return SUCCESS;
 }
 
+/**
+ * 模块请求释放
+ */
 PHP_RSHUTDOWN_FUNCTION(wing_process)
 {
 	return SUCCESS;
 }
 
+/**
+ * 模块相关的信息 phpinfo
+ */
 PHP_MINFO_FUNCTION(wing_process)
 {
 	php_info_print_table_start();
@@ -487,13 +512,14 @@ PHP_MINFO_FUNCTION(wing_process)
 
 
 const zend_function_entry wing_process_functions[] = {
-//	PHP_FE(wing_process_wait,NULL)
-//	PHP_FE(wing_create_process_ex,NULL)
+    //PHP_FE(wing_process_wait,NULL)
+    //PHP_FE(wing_create_process_ex,NULL)
 	//PHP_FE(alarm, NULL)
 	PHP_FE_END	/* Must be the last line in wing_process_functions[] */
 };
 
-zend_module_entry wing_process_module_entry = {
+zend_module_entry wing_process_module_entry =
+{
 	STANDARD_MODULE_HEADER,
 	"wing_process",
 	wing_process_functions,