Browse Source

Fixes #40 Fixing doxygen documentation

No more errors sent by doxygen
Yann Weber 4 years ago
parent
commit
4b707138ff
15 changed files with 330 additions and 190 deletions
  1. 5
    5
      docs/Doxyfile.in
  2. 4
    9
      docs/man/man1/pyfcgi.1
  3. 62
    15
      include/conf.h
  4. 5
    3
      include/ipc.h
  5. 132
    68
      include/logger.h
  6. 26
    13
      include/monitor.h
  7. 1
    1
      include/python_ioin.h
  8. 12
    10
      include/python_pyfcgi.h
  9. 14
    11
      include/pyutils.h
  10. 12
    15
      include/pyworker.h
  11. 3
    11
      include/responder.h
  12. 39
    11
      include/stats.h
  13. 8
    12
      src/main.c
  14. 4
    3
      src/python_ioin.c
  15. 3
    3
      src/pyworker.c

+ 5
- 5
docs/Doxyfile.in View File

@@ -453,7 +453,7 @@ EXTRACT_PACKAGE        = NO
453 453
 # included in the documentation.
454 454
 # The default value is: NO.
455 455
 
456
-EXTRACT_STATIC         = NO
456
+EXTRACT_STATIC         = YES
457 457
 
458 458
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
459 459
 # locally in source files will be included in the documentation. If set to NO,
@@ -690,7 +690,7 @@ SHOW_NAMESPACES        = YES
690 690
 # by doxygen. Whatever the program writes to standard output is used as the file
691 691
 # version. For an example see the documentation.
692 692
 
693
-FILE_VERSION_FILTER    = @DOXYFILE_FILE_VERSION_FILTER@
693
+FILE_VERSION_FILTER    = "git log --follow -s -n1 --format='%ai commit:%h' -- "
694 694
 
695 695
 # The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
696 696
 # by doxygen. The layout file controls the global structure of the generated
@@ -2059,7 +2059,7 @@ ENABLE_PREPROCESSING   = YES
2059 2059
 # The default value is: NO.
2060 2060
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
2061 2061
 
2062
-MACRO_EXPANSION        = NO
2062
+MACRO_EXPANSION        = YES
2063 2063
 
2064 2064
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
2065 2065
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2067,7 +2067,7 @@ MACRO_EXPANSION        = NO
2067 2067
 # The default value is: NO.
2068 2068
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
2069 2069
 
2070
-EXPAND_ONLY_PREDEF     = NO
2070
+EXPAND_ONLY_PREDEF     = YES
2071 2071
 
2072 2072
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
2073 2073
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2099,7 +2099,7 @@ INCLUDE_FILE_PATTERNS  =
2099 2099
 # recursively expanded use the := operator instead of the = operator.
2100 2100
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
2101 2101
 
2102
-PREDEFINED             = 
2102
+PREDEFINED             = __attribute__(x)=
2103 2103
 
2104 2104
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
2105 2105
 # tag can be used to specify a list of macro names that should be expanded. The

+ 4
- 9
docs/man/man1/pyfcgi.1 View File

@@ -1,18 +1,16 @@
1
-.TH "pyfcgi" 1 "Mon Oct 28 2019" "Version 0.0.1" "PyFCGI" \" -*- nroff -*-
1
+.TH "pyfcgi" 1 "Wed Dec 18 2019" "Version 0.0.1" "PyFCGI" \" -*- nroff -*-
2 2
 .ad l
3 3
 .nh
4 4
 .SH NAME
5 5
 pyfcgi \- Python Fast CGI runner
6 6
 .SH "SYNOPSIS"
7 7
 .PP
8
-spawn-fcgi [OPTS] -- pyfcgi [OPTIONS] 
8
+pyfcgi [OPTIONS] 
9 9
 .SH "DESCRIPTION"
10 10
 .PP
11 11
 Run WSGI python application in a pool of worker\&.
12 12
 .SH "OPTIONS"
13 13
 .PP
14
-.SS "spawn-fcgi OPTIONS"
15
-OPTS are \fBspawn-fcgi(1)\fP options\&.
16 14
 .SS "General OPTIONS"
17 15
 \fB-h --help\fP
18 16
 .RS 4
@@ -139,11 +137,11 @@ unix with HOST a valid PATH
139 137
 .PP
140 138
 To run foo_pep333\&.entrypoint() PEP333 application :
141 139
 .PP
142
-spawn-fcgi -d \&. -n -p 9000 -a 127\&.0\&.0\&.1 -- src/pyfcgi -S -e foo_pep333 -E entrypoint
140
+src/pyfcgi -l '127\&.0\&.0\&.1:9000' -S -e foo_pep333 -E entrypoint
143 141
 .PP
144 142
 Logfile example :
145 143
 .PP
146
-spawn-fcgi -d \&. -n -p 9000 -a 127\&.0\&.0\&.1 -- src/pyfcgi -S -e foo_pep333 -E entrypoint -L '/tmp/foo\&.log;0xff;{datetime} {msg} {ident}'
144
+src/pyfcgi -l '127\&.0\&.0\&.1:9000' -S -e foo_pep333 -E entrypoint -L '/tmp/foo\&.log;0xff;{datetime} {msg} {ident}'
147 145
 .SH "AUTHOR"
148 146
 .PP
149 147
 Written by Yann Weber <yann.weber@member.fsf.org>
@@ -152,8 +150,5 @@ Written by Yann Weber <yann.weber@member.fsf.org>
152 150
 Copyright @ 2019 Yann Weber License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licences/gpl.html>\&.
153 151
 .PP
154 152
 This is free software: you are free to change and redistribute it\&. There is NO WARRANTY, to extent permitted by law\&.
155
-.SH "See Also"
156
-.PP
157
-\fBspawn-fcgi(1)\fP
158 153
 .PP
159 154
 PyFCGI git repositorie <https://git.yannweb.net/yannweb/pyfcgi> 

+ 62
- 15
include/conf.h View File

@@ -34,22 +34,30 @@
34 34
 #include <sys/wait.h>
35 35
 
36 36
 #include "config.h"
37
-/**@defgroup conf_internal PYFCGI configuration handling
37
+/**@file conf.h 
38
+ * @brief PyFCGI configuration handling headers
39
+ * @ingroup conf_internal */
40
+
41
+/**@defgroup conf_internal PyFCGI configuration handling
42
+ * @brief Informations about PyFCGI configuration handling
38 43
  */
44
+
39 45
 /**@defgroup conf_glob PYFCGI global (for all process) configurations
40 46
  * @see struct_pyfcgi_conf_s
41 47
  * @ingroup conf_internal */
42 48
 
43
-/**@brief Friendly name for @ref struct pyfcgi_conf_s
44
- * @see struct pyfcgi_conf_s */
49
+/**@brief Friendly name for @ref pyfcgi_conf_s
50
+ * @see struct pyfcgi_conf_s
51
+ * @ingroup conf_internal */
45 52
 typedef struct pyfcgi_conf_s pyfcgi_conf_t;
46 53
 typedef struct pyfcgi_conf_logger_s pyfcgi_conf_logger_t;
47 54
 typedef struct pyfcgi_context_s pyfcgi_context_t;
48 55
 typedef struct pyfcgi_semdata_s pyfcgi_semdata_t;
49 56
 typedef struct pyfcgi_shmdata_s pyfcgi_shmdata_t;
50 57
 
51
-/**@brief Configuration globals, inherited from parent to childs
58
+/**@brief Configuration globals, inherited from parent process to childs
52 59
  * @ingroup conf_internal
60
+ * @see pyfcgi_conf_s
53 61
  */
54 62
 pyfcgi_conf_t PyFCGI_conf;
55 63
 
@@ -60,6 +68,8 @@ pyfcgi_conf_t PyFCGI_conf;
60 68
 #include "monitor.h"
61 69
 
62 70
 /**@defgroup ret_status Function & process return status
71
+ * @brief Constants
72
+ * @ingroup proc_intern
63 73
  */
64 74
 /**@ingroup ret_status */
65 75
 #define EXIT_PYERR 4
@@ -77,10 +87,13 @@ pyfcgi_conf_t PyFCGI_conf;
77 87
 /**@brief Backlog argument for socket creation */
78 88
 #define PYFCGI_SOCK_BACKLOG 100
79 89
 
80
-#define PYFCGI_NAME "spawn-fcgi [OPTIONS] -- pyfcgi"
90
+/**@brief Program name */
91
+#define PYFCGI_NAME "pyfcgi"
81 92
 
93
+/**@brief Short options specifications */
82 94
 #define PYFCGI_SHORT_OPT "C:l:e:E:Aw:W:m:ft:L:SPs:vVh"
83 95
 
96
+/**@brief Long options specifications */
84 97
 #define PYFCGI_LONG_OPT { \
85 98
 	{"config", required_argument, 0, 'C'},\
86 99
 	{"listen", required_argument, 0, 'l'},\
@@ -102,6 +115,10 @@ pyfcgi_conf_t PyFCGI_conf;
102 115
 	{0, 0, 0, 0}\
103 116
 }
104 117
 
118
+/**@brief Data for help generation
119
+ *
120
+ * For each options {HELP_TEXT, ARGS_PLACEOLDER} are specified PLACEOLDER
121
+ * is NULL for flags*/
105 122
 #define PYFCGI_OPT_HELP {\
106 123
 	{"Load options from configuration file", "CONFIG"},\
107 124
 	{"Listen socket path (a path for UNIX socket or a 'IPV4:PORT' string)", "SOCK_PATH"},\
@@ -218,8 +235,8 @@ struct pyfcgi_context_s {
218 235
 
219 236
 /**@brief Structure containing configuration
220 237
  * @ingroup conf_internal
221
- * The structure is used for the global @ref pyfcgi_conf variable.
222
- * @see pyfcgi_conf_t
238
+ * The structure is used for the global @ref PyFCGI_conf variable.
239
+ * @see pyfcgi_conf_s
223 240
  */
224 241
 struct pyfcgi_conf_s
225 242
 {
@@ -270,7 +287,7 @@ struct pyfcgi_conf_s
270 287
 	/**@brief 0 is silent 1 means logs to stderr */
271 288
 	short verbosity;
272 289
 	/**@brief Logger configuration
273
-	 * @ingroupe conf_glob */
290
+	 * @ingroup conf_glob */
274 291
 	pyfcgi_conf_logger_t logs;
275 292
 
276 293
 	/**@brief Context informations */
@@ -310,29 +327,59 @@ void default_conf();
310 327
  * @return 0 if no error */
311 328
 int parse_args(int argc, char *argv[]);
312 329
 
330
+/**@brief Check Python entrypoint import
331
+ *
332
+ * Forks into a childprocess that will start python and import the entrypoint.
333
+ * The child process exit status indicate if the import was successfull or not
334
+ * @return 0 if no errors 1 if import fails
335
+ */
313 336
 int check_entrypoint_import();
314 337
 
315
-int parse_optlog(const char*);
338
+/**@brief Parse a logger declaration option
339
+
340
+ * Expected format is : LOGFILE[;FILTER][;FMT]
341
+ * @param logspec The logspec option value
342
+ * @return 0 if no error else 1
343
+ */
344
+int parse_optlog(const char* logspec);
345
+
346
+/**@defgroup pyfcgi_watchdog PyFCGI watchdogs
347
+ * @brief Child process watchdogs mecanism
348
+ *
349
+ * @ingroup proc_intern
350
+ */
316 351
 
317 352
 /**@brief Initialize the watchdog
318
- * @param void (*wd_sig_cleaner)(int) pointer on a signal handler (or NULL to
319
- * use @ref pyfcgi_default_sighandler
320
- * @param const struct timespec* delay a pointer on the watchdog timeout
353
+ * @ingroup pyfcgi_watchdog
354
+ * @param wd_sig_cleaner pointer on a signal handler (or NULL to
355
+ * use @ref pyfcgi_wd_default_sighandler
356
+ * @param delay a pointer on the watchdog timeout
321 357
  * @return 0 if no error else -1
322 358
  */
323 359
 int pyfcgi_wd_init(void (*wd_sig_cleaner)(int), const struct timespec *delay);
360
+/**@brief (Re)starts watchdog timer
361
+ * @ingroup pyfcgi_watchdog
362
+ *@return 0 if no error else -1 */
324 363
 int pyfcgi_wd_arm();
364
+/**@brief Temporarly disables watchdog
365
+ * @ingroup pyfcgi_watchdog
366
+ *@return 0 if no error else -1 */
325 367
 int pyfcgi_wd_pause();
368
+/**@brief Stop and delete a watchdog
369
+ * @ingroup pyfcgi_watchdog
370
+ * @return 0 if no error else -1*/
326 371
 int pyfcgi_wd_stop();
327 372
 
328
-/**@brief Watchdog default signal handler */
373
+/**@brief Watchdog default signal handler
374
+ * @ingroup pyfcgi_watchdog
375
+ * @param signum signal number*/
329 376
 void pyfcgi_wd_default_sighandler(int signum);
330 377
 
331 378
 /**@brief Return a string representing a status
332
- * @param int status
379
+ * @param status Status
333 380
  * @return a char* that should be freed
334 381
  */
335
-char *status2str(int);
382
+char *status2str(int status);
336 383
 
337 384
 void pyfcgi_sighandler_drop(int signum);
338 385
 

+ 5
- 3
include/ipc.h View File

@@ -17,6 +17,8 @@
17 17
  * along with PyFCGI.  If not, see <http://www.gnu.org/licenses/>.
18 18
  */
19 19
 /**@defgroup IPC Inter process communication mechanism
20
+ * @brief IPC mechanism
21
+ * @ingroup proc_intern
20 22
  */
21 23
 /**@file ipc.h
22 24
  * @ingroup IPC */
@@ -68,18 +70,18 @@ typedef unsigned short pyfcgi_ipc_flag_t;
68 70
 #include "stats.h" //to get SHM size
69 71
 
70 72
 /**@brief Set semaphore names using master process PID as uniq key
71
- * @param pid_t master process PID
73
+ * @param master_pid master process PID
72 74
  */
73 75
 void pyfcgi_name_IPC(pid_t master_pid);
74 76
 
75 77
 /**@brief Do shm_open & sem_open given component indicated by flag
76
- * @param pyfcgi_ipc_flah_t flag a binary or combination of component flags
78
+ * @param flag a binary or combination of component flags
77 79
  * @return 0 if no error else -1
78 80
  * @note Stores the flag in configuration context 
79 81
  * @see IPC_flags
80 82
  */
81 83
 int pyfcgi_IPC_init(pyfcgi_ipc_flag_t flag);
82
-/**@brief Same than @ref pyfchi_IPC_init but with O_CREAT flag set */
84
+/**@brief Same than @ref pyfcgi_IPC_init but with O_CREAT flag set */
83 85
 int pyfcgi_IPC_create(pyfcgi_ipc_flag_t flag);
84 86
 
85 87
 /**@brief Close previously opened IPC component (from conf context stored flag)

+ 132
- 68
include/logger.h View File

@@ -1,7 +1,7 @@
1 1
 /*
2 2
  * Copyright (C) 2019 Weber Yann
3 3
  * 
4
- * This file is part of PyFCGI.
4
+ * This file is part mf PyFCGI.
5 5
  * 
6 6
  * PyFCGI is free software: you can redistribute it and/or modify
7 7
  * it under the terms of the GNU Affero General Public License as published by
@@ -34,15 +34,19 @@
34 34
 #include <sys/stat.h>
35 35
 
36 36
 /**@file logger.h
37
- * @brief PyFCGI logging facility
37
+ * @brief PyFCGI logging handling headers
38 38
  * @ingroup conf_logger
39 39
  */
40
+
40 41
 /**@defgroup conf_logger Logging configuration
42
+ * @brief Informations about PyFCGI logger configuration
41 43
  * @ingroup conf_internal
42 44
  * @ingroup logging
43 45
  */
44 46
 
45
-/**@defgroup log_facility Logger custom facilities */
47
+/**@defgroup log_facility Logger custom facilities
48
+ * @ingroup conf_logger
49
+ */
46 50
 /**@ingroup log_facility */
47 51
 #define LOG_GLOBAL 0
48 52
 /**@ingroup log_facility */
@@ -58,7 +62,7 @@
58 62
 #define PYFCGI_LOGGER_FMT_MAX PYFCGI_LOGGER_MAX
59 63
 #define PYFCGI_LOGGER_FIELD_MAX 24
60 64
 #define PYFCGI_LOGGER_FMT_PARSE_ERRSZ 64
61
-/**@brief The size of the @ref struct pyfcgi_logger_format_t.buf allocated to
65
+/**@brief The size of the @ref pyfcgi_logger_format_t.buf allocated to
62 66
  * the message field */
63 67
 #define PYFCGI_LOGGER_MSG_BUF_SZ 64
64 68
 
@@ -103,35 +107,40 @@
103 107
 #define PYFCGI_SYSLOG_LVL(lvl) (((lvl & 0xF0) >> 4)-1)
104 108
 
105 109
 /**@brief Macro checking if syslog is activated and log a message
106
- * @params int lvl the PyFCGI log level
107
- * @param char* fmt the message format
110
+ * @param lvl the PyFCGI log level
111
+ * @param fmt the message format
112
+ * @param ... format arguments
108 113
  * @see _vsyslog syslog
109 114
  */
110
-#define _syslog(lvl, ...) if(conf->flags & PYFCGI_LOG_FSYSLOG) { \
111
-	syslog(PYFCGI_SYSLOG_LVL(lvl), __VA_ARGS__);\
112
-}
113
-#define _vsyslog(lvl, fmt, ap) if(conf->flags & PYFCGI_LOG_FSYSLOG) { \
114
-	vsyslog(PYFCGI_SYSLOG_LVL(lvl), fmt, ap);\
115
+#define _syslog(lvl, fmt, ...) if(conf->flags & PYFCGI_LOG_FSYSLOG) { \
116
+	syslog(PYFCGI_SYSLOG_LVL(lvl), fmt,  __VA_ARGS__);\
115 117
 }
116 118
 
117 119
 /**@brief Macro checking if syslog is activated and log a message using PyFCGI
118 120
  * loglevels
119
- * @params int lvl the PyFCGI log level
120
- * @param char* fmt the message format
121
+ * @param lvl the PyFCGI log level
122
+ * @param fmt the message format
123
+ * @param ap va_list fmt arguments
121 124
  * @see vsyslog _syslog
122 125
  */
126
+#define _vsyslog(lvl, fmt, ap) if(conf->flags & PYFCGI_LOG_FSYSLOG) { \
127
+	vsyslog(PYFCGI_SYSLOG_LVL(lvl), fmt, ap);\
128
+}
123 129
 
124 130
 
125
-/**@defgroup conf_logger_flags Logger confifurations flags
131
+/**@defgroup conf_logger_flags Logger configurations flags
132
+ * @brief Constants for logger configuration 
126 133
  * @ingroup conf_logger */
127
-/**@ingroup cong_logger_flags */
134
+
135
+/**@brief Indicate if syslog should be used
136
+ * @ingroup cong_logger_flags */
128 137
 #define PYFCGI_LOG_FSYSLOG 1
129 138
 /**@brief Indicate if the logger should try to reopen on failure
130
- * @warn not implemented
139
+ * @warning not implemented
131 140
  * @ingroup cong_logger_flags */
132 141
 #define PYFCGI_LOG_FRETRY 2
133 142
 /**@brief Exit if failure
134
- * @warn not implemented
143
+ * @warning not implemented
135 144
  * @ingroup cong_logger_flags */
136 145
 #define PYFCGI_LOG_FEXIT_ONFAIL 4
137 146
 
@@ -156,7 +165,7 @@ typedef struct strftime_args_s strftime_args_t;
156 165
 typedef struct ident_args_s ident_args_t;
157 166
 typedef union pyfcgi_logger_field_args pyfcgi_logger_field_args_u;
158 167
 
159
-
168
+/**@brief Stores log message level's names */
160 169
 static const char* PYFCGI_LOGGER_LVLNAME[] __attribute__((unused)) = {
161 170
 	" Emerge",
162 171
 	"  Alert",
@@ -167,12 +176,19 @@ static const char* PYFCGI_LOGGER_LVLNAME[] __attribute__((unused)) = {
167 176
 	"   Info",
168 177
 	"  Debug"};
169 178
 
179
+
180
+/**@brief Stores log message facility's names 
181
+ * @ingroup log_facility
182
+ * @see pyfcgi_logger_value_facility */
170 183
 static const char* PYFCGI_LOGGER_TYPNAME[] __attribute__((unused)) =
171 184
 	{"Global", "Access", "Internal", "Worker", "Master"} ;
172 185
 
173 186
 
174 187
 /**@defgroup conf_logger_format Logline format
188
+ * @brief Informations about logline format configuration
189
+ *
175 190
  * @ingroup conf_logger
191
+ *
176 192
  * A small description langage allows to describe wanted logline format.
177 193
  * A format is a string with special markup indicating fields. Fields markup
178 194
  * are surrounded by '{' and '}' chr. This markup can be divided in multiple
@@ -214,18 +230,29 @@ union pyfcgi_logger_field_args
214 230
 	ident_args_t ident;
215 231
 };
216 232
 
217
-/**@brief Logger format field's type
218
- * @ingroup conf_logger_format */
233
+/**@brief Logger field's type
234
+ * @ingroup conf_logger_format
235
+ * @see pyfcgi_logger_fmt_field_s
236
+ */
219 237
 enum pyfcgi_logger_field_type
220 238
 {
239
+	/** Null value */
221 240
 	pyfcgi_logger_field_null = 0,
241
+	/** Constant string field */
222 242
 	pyfcgi_logger_field_const = -1,
243
+	/** Datetime field */
223 244
 	pyfcgi_logger_field_datetime = 1,
245
+	/** Loglevel name field */
224 246
 	pyfcgi_logger_field_level = 2,
247
+	/** Log facility name field */
225 248
 	pyfcgi_logger_field_facility = 3,
249
+	/** PID field */
226 250
 	pyfcgi_logger_field_pid = 4,
251
+	/** Parent PID field */
227 252
 	pyfcgi_logger_field_ppid = 5,
253
+	/** Logger identity field */
228 254
 	pyfcgi_logger_field_ident = 6,
255
+	/** Message field */
229 256
 	pyfcgi_logger_field_msg = 7,
230 257
 };
231 258
 
@@ -233,13 +260,17 @@ enum pyfcgi_logger_field_type
233 260
  * @ingroup conf_logger_format */
234 261
 struct pyfcgi_logger_fmt_field_s
235 262
 {
263
+	/** @brief Field type */
236 264
 	pyfcgi_logger_field_type_e type;
237 265
 
266
+	/** @brief Flag indicating if field len is known (may be unused...) */
238 267
 	short known_length;
268
+	/** @brief Field len */
239 269
 	size_t len;
240 270
 
241 271
 	/** @brief pointer on value (interpreted given field type) */
242 272
 	void *val;
273
+	/** @brief Field argument (datetime or ident) */
243 274
 	pyfcgi_logger_field_args_u args;
244 275
 	/**@brief Points in prefix or sufix buffer */
245 276
 	char *buf_ptr;
@@ -267,7 +298,9 @@ struct pyfcgi_logger_format_s
267 298
 	/**@brief Message suffix */
268 299
 	char *suffix;
269 300
 
301
+	/**@brief Message pointer */
270 302
 	char *_msg;
303
+	/**@brief Message len */
271 304
 	size_t _msglen;
272 305
 };
273 306
 
@@ -276,11 +309,16 @@ struct pyfcgi_logger_format_s
276 309
  */
277 310
 struct pyfcgi_logger_s
278 311
 {
312
+	/**@brief Logfile name */
279 313
 	char *filename;
314
+	/**@brief Logfile FD */
280 315
 	int fd;
316
+	/**@brief Loglevel mask */
281 317
 	logmask_t loglvl;
318
+	/**@brief Logfacility mask */
282 319
 	logmask_t logtyp;
283 320
 
321
+	/**@brief Logline format ID ref @ref pyfcgi_conf_logger_s.formats */
284 322
 	size_t fmt_id;
285 323
 };
286 324
 
@@ -289,27 +327,37 @@ struct pyfcgi_logger_s
289 327
  */
290 328
 struct pyfcgi_conf_logger_s
291 329
 {
292
-	/**@brief Or combination of @ref PYFCGI_LOG_SYSLOG or
293
-	 * @ref PYFCGI_LOG_RETRY */
330
+	/**@brief Or combination of @ref PYFCGI_LOG_FSYSLOG or
331
+	 * @ref PYFCGI_LOG_FRETRY */
294 332
 	short flags;
333
+	/**@brief Syslog ident string */
295 334
 	char *syslog_ident;
335
+	/**@brief Syslog facility */
296 336
 	int syslog_facility;
337
+	/**@brief Syslog logger minimum loglevel */
297 338
 	logmask_t syslog_loglvl;
339
+	/**@brief Syslog logger PyFCGI facilities */
298 340
 	logmask_t syslog_logtyp;
299 341
 
300 342
 	/**@brief PyFCGI internal ident, prefixes all log messages */
301 343
 	char *ident;
344
+	/**@brief PyFCGI current facility @ref pyfcgi_logger_field_type */
302 345
 	logmask_t facility;
303 346
 
347
+	/**@brief List of loggers */
304 348
 	pyfcgi_logger_t loggers[PYFCGI_LOGGER_MAX];
349
+	/**@brief Logger count */
305 350
 	unsigned char logger_sz;
306 351
 
352
+	/**@brief List of logger formats */
307 353
 	pyfcgi_logger_format_t formats[PYFCGI_LOGGER_MAX];
308 354
 	//char **format;
355
+	/**@brief Logger formats count */
309 356
 	unsigned char format_sz;
310 357
 
311 358
 	/**@brief Buffer for message field formating */
312 359
 	char *msg_buf;
360
+	/**@brief Message buffer len */
313 361
 	size_t msg_buf_sz;
314 362
 
315 363
 	/**@brief Internal pipe to tee(2) the message on loggers (USELESS)*/
@@ -326,80 +374,86 @@ int pyfcgi_logger_init();
326 374
 int pyfcgi_logger_stop();
327 375
 
328 376
 /**@brief Enable syslog logging with given ident
329
- * @param char* ident if NULL use current ident
377
+ * @param ident if NULL use current ident
330 378
  */
331
-void pyfcgi_logger_enable_syslog(const char*);
379
+void pyfcgi_logger_enable_syslog(const char* ident);
332 380
 
333
-/**@brief Stop & free an individual logger */
334
-void _pyfcgi_logger_free(pyfcgi_logger_t*);
381
+/**@brief Stop & free an individual logger
382
+ * @param logger
383
+ */
384
+void _pyfcgi_logger_free(pyfcgi_logger_t* logger);
335 385
 
336 386
 /**@brief Add a new logger
337
- * @param char* filename or NULL if stderr (fd 2 ) wanted
338
- * @param logmask_t loglvl a mask indicating wich loglevels should be logged
339
- * @param logmask_t typemask a mask indicating wich facility should be logged
340
- * @param char* log format (or NULL for default format)
387
+ * @param filename or NULL if stderr (fd 2 ) wanted
388
+ * @param loglvl a mask indicating wich loglevels should be logged
389
+ * @param logtyp a mask indicating wich facility should be logged
390
+ * @param format log format (or NULL for default format)
341 391
  */
342
-int pyfcgi_logger_add(const char*, logmask_t, logmask_t, const char*);
392
+int pyfcgi_logger_add(const char* filename, logmask_t loglvl, logmask_t logtyp,
393
+	const char* format);
343 394
 
344 395
 /**@brief Add a new format
345
- * @param char *format
346
- * @param size_t* idx if not NULL, will contain the format index
396
+ * @param format
397
+ * @param idx if not NULL, will contain the format index
347 398
  * @return 0 if OK
348 399
  */
349
-int pyfcgi_logger_format_add(const char*, size_t*);
400
+int pyfcgi_logger_format_add(const char* format, size_t* idx);
350 401
 
351 402
 /**@brief Parse a format string and populate corresponding 
352
- * @ref struct pyfgci_logger_format_s
353
- * @param const char* fmt string
354
- * @param pyfcgi_logger_format_t* fmt_data
403
+ * @ref pyfcgi_logger_format_s
404
+ * @param fmt_string format string
405
+ * @param fmt_data
355 406
  * @return 0 if no errors
356 407
  */
357
-int pyfcgi_logger_parse_format(const char*, pyfcgi_logger_format_t*);
408
+int pyfcgi_logger_parse_format(const char* fmt_string,
409
+	pyfcgi_logger_format_t* fmt_data);
358 410
 
359 411
 /**@brief Initialize a pyfcgi_logger_format_t.buf attribute (to init the
360 412
  * prefix & sufix attributes.
361 413
  * @note have to be called when ident is updated
362
- * @param pyfcgi_logger_format_t* fmt
363
- * @note called by @ref pyfcgi_logger_add_format but should be called
414
+ * @param fmt
415
+ * @note called by @ref pyfcgi_logger_format_add but should be called
364 416
  * by @ref pyfcgi_logger_parse_format
365 417
  */
366
-int pyfcgi_logger_format_bufinit(pyfcgi_logger_format_t*);
418
+int pyfcgi_logger_format_bufinit(pyfcgi_logger_format_t* fmt);
367 419
 
368 420
 /**@brief Parse a field string and populate corresponding
369
- * @ret struct pyfcgi_logger_field_s
370
- * @param const char ** ptr on current format pointer
371
- * @param char * if not NULL and parse error occurs, this string
421
+ * @ref pyfcgi_logger_fmt_field_s
422
+ * @param ptr on current format pointer
423
+ * @param start if not NULL and parse error occurs, this string
372 424
  * will be set
425
+ * @param cur_field Current field
426
+ * @param fail_reason stores a parse failure reason on error
373 427
  * @return 0 if no errors and 1 if parse error
374 428
  */
375
-int pyfcgi_logger_parse_field(const char**, const char *,
376
-                              pyfcgi_logger_fmt_field_t*,
377
-                              char[PYFCGI_LOGGER_FMT_PARSE_ERRSZ]);
429
+int pyfcgi_logger_parse_field(const char** ptr, const char * start,
430
+                              pyfcgi_logger_fmt_field_t* cur_field,
431
+                              char fail_reason[PYFCGI_LOGGER_FMT_PARSE_ERRSZ]);
378 432
 
379 433
 /**@brief Free allocated memory in given field
380
- * @param pyfcgi_logger_fmt_field_t* field to free
434
+ * @param field field to free
381 435
  */
382
-void pyfcgi_logger_field_free(pyfcgi_logger_fmt_field_t*);
436
+void pyfcgi_logger_field_free(pyfcgi_logger_fmt_field_t* field);
383 437
 
384 438
 /**@brief Given a field pointer return the size option incrementing
385 439
  * ptr
386 440
  * @warning do not check if the next character is OK, the caller has to
387 441
  * do it
388
- * @param char** pointer on format
389
- * @param size_t* size if found will be set to size option. if not found set to
442
+ * @param ptr pointer on format
443
+ * @param size if found will be set to size option. if not found set to
390 444
  * 0
391 445
  * @return 0 if no error
392 446
  */
393
-int pyfcgi_logger_parse_field_sz(const char**, size_t*);
447
+int pyfcgi_logger_parse_field_sz(const char** ptr, size_t* size);
394 448
 
395 449
 /**@brief Alloc memory by parsing & strdup the strftime format found
396 450
  * in field. If not found use default format
397
- * @note set the @ref struct pyfcgi_logger_fmt_field_s.args field
398
- * @param const char** ptr
399
- * @param char** format
400
- * @return 
451
+ * @note set the @ref pyfcgi_logger_fmt_field_s.args field
452
+ * @param ptr Pointer on current chr
453
+ * @param format strftime format result
454
+ * @return 0 or PYFCGI_FATAL
401 455
  */
402
-int pyfcgi_logger_parse_field_dtfmt(const char**, char**);
456
+int pyfcgi_logger_parse_field_dtfmt(const char** ptr, char** format);
403 457
 
404 458
 /**@brief Return a str repr of given loglevel
405 459
  * @warning returned pointer must NOT be freed or modified
@@ -409,32 +463,42 @@ const char* pyfcgi_logger_value_level(short);
409 463
 const char* pyfcgi_logger_value_facility(short);
410 464
 
411 465
 /**@brief Open a logger
412
- * @param pyfcgi_logger_t
466
+ * @param logger The logger to open
413 467
  * @return 0 if no errors
414 468
  */
415
-int pyfcgi_logger_open(pyfcgi_logger_t*);
469
+int pyfcgi_logger_open(pyfcgi_logger_t* logger);
416 470
 
417 471
 /**@brief Set programm identity for logger
418 472
  * @note ident is global to a process
419 473
  * @note this function triggers the refresh of the loggers internal
420 474
  * buffers if needed (see @ref pyfcgi_logger_format_bufinit() )
421
- * @param const char* new_ident
475
+ * @param new_ident new identity
422 476
  * @return 0 if no error
423 477
  */
424
-int pyfcgi_logger_set_ident(const char*);
478
+int pyfcgi_logger_set_ident(const char* new_ident);
425 479
 
426
-/**@brief Format a message using a @ref struct pyfcgi_logger_format_s
480
+/**@brief Format a message using a @ref pyfcgi_logger_format_s
427 481
  * @note alloc and write the logline in the attribute _msg
428
- * @param pyfcgi_logger_format_t the pyfcgi logger format structure
429
- * @param loglvl_t the loglevel (see @ref pyfcgi_log() )
430
- * @param char* message the message sent by user
431
- * @param size_t len the message len
482
+ * @param fmt the pyfcgi logger format structure
483
+ * @param lvl the loglevel (see @ref pyfcgi_log() )
484
+ * @param message the message sent by user
485
+ * @param len the message len
432 486
  * @return NULL if error
433 487
  */
434 488
 char* vpyfcgi_logger_format_message(pyfcgi_logger_format_t *fmt,
435 489
 	loglvl_t lvl, const char* message, size_t len);
436 490
 
437
-int pyfcgi_log(loglvl_t, const char*, ...);
438
-int vpyfcgi_log(loglvl_t, const char*, va_list);
491
+/**@brief Logging function
492
+ * @param lvl Loglevel
493
+ * @param fmt Message in printf format
494
+ * @param ... fmt arguments
495
+ */
496
+int pyfcgi_log(loglvl_t lvl, const char* fmt, ...);
497
+/**@brief Logging function
498
+ * @param lvl Loglevel
499
+ * @param fmt Message in printf format
500
+ * @param ap fmt arguments
501
+ */
502
+int vpyfcgi_log(loglvl_t lvl, const char* fmt, va_list ap);
439 503
 
440 504
 #endif

+ 26
- 13
include/monitor.h View File

@@ -17,10 +17,20 @@
17 17
  * along with PyFCGI.  If not, see <http://www.gnu.org/licenses/>.
18 18
  */
19 19
 
20
-/**@defgroup monitoring Monitoring a running PyFCGI
20
+/**@defgroup monitor_proc Monitoring process
21
+ * @brief Collect informations and run a monitoring server providing statistics
22
+ * @ingroup main_proc
23
+ */
24
+/**@defgroup monitoring Monitoring server
25
+ * @brief A small UDP server for monitoring
21 26
  *
22 27
  * PyFCGI have the ability to listen on a UDP socket, replying to simple
23 28
  * queries (or simple stats).
29
+ * @ingroup monitor_proc
30
+ */
31
+/**@file monitor.h
32
+ * @brief Monitoring server headers
33
+ * @ingroup monitoring
24 34
  */
25 35
 #ifndef _MONITOR__H___
26 36
 #define _MONITOR__H___
@@ -86,34 +96,37 @@ void pyfcgi_monitor_stream_loop();
86 96
 void pyfcgi_monitor_dgram_loop();
87 97
 
88 98
 /**@brief Check socket URL validity
89
- * @param const char* the URL to check
99
+ * @param sockurl the URL to check
90 100
  * @return -1 if error else 0
91 101
  * @note Logs error using dprintf(2, ...) because this function will
92 102
  * be called when checking configuration
93 103
  */
94
-int pyfcgi_monitor_check_sock(const char*);
104
+int pyfcgi_monitor_check_sock(const char* sockurl);
95 105
 
96 106
 /**@brief Parse stored socket URL
97
- * @param const char* the URL to parse
98
- * @param int[3] socket creation arguments
99
- * @param pyfcgi_monitor_addr_t the addr to bind to
107
+ * @param sockurl the URL to parse
108
+ * @param sockargs socket creation arguments
109
+ * @param listen_addr the addr to bind to
100 110
  * @return 0 if no error else -1
101 111
  * @todo add support for xxx://[IPV6]:port
102 112
  */
103
-int pyfcgi_monitor_parse_sock(const char*, int[3], pyfcgi_monitor_addr_t*);
113
+int pyfcgi_monitor_parse_sock(const char* sockurl, int sockargs[3],
114
+	pyfcgi_monitor_addr_t* listen_addr);
104 115
 
105 116
 /**@brief Parse an addres:port string in a sockaddr_in
106
- * @param const char* the hostname:port string
107
- * @param int socket family
108
- * @param pyfcgi_monitor_addr_t* the addr pointer
109
- * @param int* if not NULL will be set to choosen domain
117
+ * @param addr_str the hostname:port string
118
+ * @param socktype socket family
119
+ * @param listen_addr the addr pointer
120
+ * @param domain if not NULL will be set to choosen domain
110 121
  * @return 0 if no erro else -1
111 122
  * @todo add support for xxx://[IPV6]:port
112 123
  */
113
-int pyfcgi_monitor_parse_inet_addr(const char*, int, pyfcgi_monitor_addr_t*,
114
-	int*);
124
+int pyfcgi_monitor_parse_inet_addr(const char* addr_str, int socktype,
125
+	pyfcgi_monitor_addr_t* listen_addr, int* domain);
115 126
 
127
+/**@brief Monitor process sighandler */
116 128
 void pyfcgi_monitor_sighandler(int signum);
129
+/**@brief Monitor timeout sighandler */
117 130
 void pyfcgi_monitor_timeout(int signum);
118 131
 
119 132
 #endif

+ 1
- 1
include/python_ioin.h View File

@@ -20,7 +20,7 @@
20 20
 /**@defgroup lib_ioin Defines libpyfcgi.IoIn class
21 21
  * @brief The IoIn class implement base IO interface allowing python to read
22 22
  * HTTP request from FCGI
23
- * @ingroup libpyfcgo
23
+ * @ingroup libpyfcgi
24 24
  */
25 25
 /**@file python_ioin.h
26 26
  * @ingroup lib_ioin

+ 12
- 10
include/python_pyfcgi.h View File

@@ -112,7 +112,7 @@ static inline void libpyfcgi_clean_response()
112 112
 void libpyfcgi_send_headers();
113 113
 
114 114
 /**@brief Send body to fcgi
115
- * @param PyObject* the body data object (returned by PEP333 app)
115
+ * @param body_data the body data object (returned by PEP333 app)
116 116
  * @return Python None
117 117
  */
118 118
 PyObject* _pyfcgi_write_body(PyObject *body_data);
@@ -138,26 +138,28 @@ PyMODINIT_FUNC PyInit_libpyfcgi(void);
138 138
  * @ingroup libpyfcgi
139 139
  * @note This python callable is a fastcall C method of libpyfcgi module.
140 140
  * 
141
- * The python function header is : start_response(status, response_headers, exc_info = None)
142
- * @param PyObject* self
143
- * @param PyObject* argv
144
- * @param Py_ssize_t argc
141
+ * The python function header is :
142
+ * start_response(status, response_headers, exc_info = None)
143
+ * @param self
144
+ * @param argv
145
+ * @param argc
145 146
  * @return A PyObject* referencing a callable allowing to write data without
146 147
  * cache : libpyfcgi.write_body()
147 148
  */
148
-PyObject* pyfcgi_start_response(PyObject*, PyObject**, Py_ssize_t);
149
+PyObject* pyfcgi_start_response(PyObject* self, PyObject** argv,
150
+	Py_ssize_t argc);
149 151
 
150 152
 /**@brief libpyfcgi.write_body() python callable
151 153
  * @ingroup libpyfcgi
152 154
  * @note This python callable is a fastcall C method of libpyfcgi module.
153 155
  *
154 156
  * The python function header is : write_body(body_data)
155
- * @param PyObject* self
156
- * @param PyObject* argv
157
- * @param Py_ssize_t argc
157
+ * @param self
158
+ * @param argv
159
+ * @param argc
158 160
  * @return ???
159 161
  */
160
-PyObject* pyfcgi_write_body(PyObject*, PyObject**, Py_ssize_t);
162
+PyObject* pyfcgi_write_body(PyObject* self, PyObject** argv, Py_ssize_t argc);
161 163
 
162 164
 int _libpyfcgi_stdout_write(const char*, size_t);
163 165
 int _libpyfcgi_stderr_write(const char*, size_t);

+ 14
- 11
include/pyutils.h View File

@@ -45,28 +45,31 @@ void pyinit();
45 45
 void update_python_path();
46 46
 
47 47
 /**@brief Fetch stdout & stderr python flush() function
48
- * @param PyObject* pystdout_flush
49
- * @param PyObject* pystderr_flush
48
+ * @param pystdout_flush will point on &sys.stdout.flush() python function
49
+ * @param pystderr_flush will point on &sys.stderr.flush() python function
50 50
  */
51
-void fetch_pyflush(PyObject**, PyObject**);
51
+void fetch_pyflush(PyObject** pystdout_flush, PyObject** pystderr_flush);
52 52
 
53 53
 /**@brief Create two pipes for stdout & stderr
54 54
  * @ingroup worker_process
55
- * @params int[2] pystdout
56
- * @params int[2] pystderr
55
+ * @param pipe_out pipe for stdout
56
+ * @param pipe_err pipe for stderr
57
+ * @warning Deprecated behavior. We will us ioin like classes for std & err
58
+ * output
57 59
  */
58
-void update_python_fd(int[2], int[2]);
60
+void update_python_fd(int pipe_out[2], int pipe_err[2]);
59 61
 
60
-/**@brief Clear then update python sys.environ using current FCI environ
62
+/**@brief Clear then update python sys.environ using current FCGI environ
61 63
  * @ingroup worker_process
62 64
  * @note The environ has to be set without a call to os.putenv, the problem
63 65
  * is that the os.environ is a special mapping calling putenv on setitem...
64 66
  * For these reason the os.environ will be replaced by a new dict instance for
65 67
  * each request...
66
- * @param PyObject* os module
68
+ * @param py_osmod Python os module
69
+ * @param environ The environ string provided by libfcgi
67 70
  * @return Python env dict
68 71
  */
69
-PyObject* update_pyenv(PyObject*, char**);
72
+PyObject* update_pyenv(PyObject* py_osmod, char** environ);
70 73
 
71 74
 /**@brief Import & return the python entrypoint callable
72 75
  * from PyFCGI_conf.py_entrymod & PyFCGI_conf.py_entryfun */
@@ -82,8 +85,8 @@ PyObject* get_start_response();
82 85
 void log_expt(int priority);
83 86
 
84 87
 /**@brief Set python version
85
- * @param char[16] version buffer */
86
-void pyfcgi_python_version(char[16]);
88
+ * @param version version buffer */
89
+void pyfcgi_python_version(char version[16]);
87 90
 
88 91
 /**@brief Import os module and exit on error
89 92
  * @return Imported module */

+ 12
- 15
include/pyworker.h View File

@@ -48,7 +48,6 @@
48 48
  *
49 49
  * @see update_python_path()
50 50
  *
51
- * @ingroup processes
52 51
  * @ingroup work_master_proc
53 52
  */
54 53
 /**@file pyworker.h
@@ -108,24 +107,22 @@ extern PyObject* response_headers;
108 107
  * This function handles python worker by running a PEP333 application function.
109 108
  * The start_response() function set @ref response_status and
110 109
  * @ref response_headers globals.
111
- * @param char* python_entrypoint a path to a python entrypoint
112
- * @param int worker uid
110
+ * @param wrk_id worker id
113 111
  * @return 0 if exit avec max requests
114 112
  */
115
-int work333(int);
113
+int work333(int wrk_id);
116 114
 
117 115
 /**@brief the function that initialize the alternate python worker
118 116
  * @ingroup worker_process
119 117
  *
120 118
  * This function handles python worker using stdout to communicate with
121 119
  * FCGI. This function clones for each request, running worker_piper()
122
- * @param char* python_entrypoint a path to a python entrypoint
123
- * @param int worker uid
120
+ * @param wrk_id worker id
124 121
  * @return 0 if exit avec max requests
125 122
  */
126
-int work(int);
123
+int work(int wrk_id);
127 124
 
128
-/**@brief function for a subprocess designed to read stdin & stdout from
125
+/*/**@brief function for a subprocess designed to read stdin & stdout from
129 126
  * python & forward them to syslog or FCGI
130 127
  * @ingroup worker_process
131 128
  * @param int worker id
@@ -149,18 +146,18 @@ void worker_piper_sighandler(int);
149 146
  * @todo enhance logging : 1 lines per logline + line counter ?
150 147
  * @todo sys.stdout & sys.stderr can have an implementation like
151 148
  * libpyfcgi.IoIn to avoir useless buffering
152
- * @param int pipes for stdout
153
- * @param int pipes for stderr
154
- * @param PyObject[2] python flush methods
149
+ * @param pipe_std pipe for stdout
150
+ * @param pipe_err pipe for stderr
151
+ * @param flush python flush methods 
155 152
  */
156
-void worker_log_pipes(int, int, PyObject*[2]);
153
+void worker_log_pipes(int pipe_std, int pipe_err, PyObject* flush[2]);
157 154
 
158 155
 /**@brief Attempt to read the request size from ctl pipe
159
- * @param int ctl pipe read fd
160
- * @param size_t* rep_sz
156
+ * @param ctl_pipe read fd
157
+ * @param rep_sz response size
161 158
  * @return 0 if no error
162 159
  */
163
-int ctl_get_rep_sz(int, size_t*);
160
+int ctl_get_rep_sz(int ctl_pipe, size_t* rep_sz);
164 161
 
165 162
 void worker_sighandler(int);
166 163
 void worker_sigalrmhandler(int signum);

+ 3
- 11
include/responder.h View File

@@ -32,7 +32,6 @@
32 32
  * idle. Instead, if the semtimedop returns imediately it means a new worker
33 33
  * can be spawned.
34 34
  *
35
- * @ingroup processes
36 35
  * @ingroup main_proc
37 36
  */
38 37
 /**@file responder.h
@@ -67,13 +66,6 @@ pid_t spawn_pool_handler();
67 66
 /**@brief The responder loop
68 67
  * @ingroup work_master_proc
69 68
  * The main function of the fcgi app fork child
70
- * @param int max_requests : exit normally after this number of requests. If
71
- * 0 given never exit.
72
- * @param char* python_entrymodule a python module name
73
- * @param char* python_entrymodule a python callable name from entry module
74
- * @param unsigned int max_requests before exiting worker
75
- * @param unsigned int minimum workers count
76
- * @param unsigned int maximum wrokers count
77 69
  * @return 0 on success
78 70
  */
79 71
 int responder_loop();
@@ -82,16 +74,16 @@ int responder_loop();
82 74
 /**@brief Spawn a worker given an entrypoint
83 75
  * @ingroup work_master_proc
84 76
  * Spawn a new worker process and prepare ENV & request forwarding
85
- * @param int worker uid
77
+ * @param wrk_id worker id
86 78
  * @return child PID
87 79
  */
88
-pid_t spawn(int);
80
+pid_t spawn(int wrk_id);
89 81
 
90 82
 
91 83
 /**@deprecated Not used */
92 84
 int pyfcgi_pool_state();
93 85
 /**@brief Check if the pool is idle : if not able to timedwait the pool is busy
94
- * @param const struct timespec timeout
86
+ * @param timeout
95 87
  * @return 1 if busy else 0
96 88
  * @note exit on error
97 89
  */

+ 39
- 11
include/stats.h View File

@@ -16,6 +16,10 @@
16 16
  * You should have received a copy of the GNU Affero General Public License
17 17
  * along with PyFCGI.  If not, see <http://www.gnu.org/licenses/>.
18 18
  */
19
+/**@defgroup stats PyFCGI statistics
20
+ * @brief Information about statistics collection mechanism
21
+ * @ingroup monitor_proc
22
+ */
19 23
 /**@file stats.h
20 24
  * @ingroup monitoring */
21 25
 #ifndef _STATS__H___
@@ -28,7 +32,9 @@
28 32
 #include <signal.h>
29 33
 #include <string.h>
30 34
 
35
+/**@brief Stats history size (900 = 900s = 15min) */
31 36
 #define PYFCGI_STATS_SZ (900)
37
+/**@brief Signal used to wake up stats server in order to collect stats*/
32 38
 #define PYFCGI_STATS_SIGALRM 30
33 39
 
34 40
 typedef struct pyfcgi_stats_s pyfcgi_stats_t;
@@ -38,7 +44,9 @@ typedef struct pyfcgi_stats_shm_s pyfcgi_stats_shm_t;
38 44
 #include "conf.h"
39 45
 #include "logger.h"
40 46
 
41
-/**@brief Stores data for stats on 15min (900s) */
47
+/**@brief Stores data for stats on 15min (900s)
48
+ * @ingroup stats
49
+ */
42 50
 struct pyfcgi_stats_sample_s
43 51
 {
44 52
 	/**@brief One sample per seconds */
@@ -47,6 +55,9 @@ struct pyfcgi_stats_sample_s
47 55
 	int cur;
48 56
 };
49 57
 
58
+/**@brief Stores statistics informations
59
+ * @ingroup stats
60
+ */
50 61
 struct pyfcgi_stats_s
51 62
 {
52 63
 	/**@brief Request per seconds on 15 minutes */
@@ -68,9 +79,14 @@ struct pyfcgi_stats_s
68 79
 	size_t buff_len;
69 80
 };
70 81
 
82
+/**@brief Stores stats information on worker count & load average
83
+ * @note Data are updated by @ref work_master_proc
84
+ */
71 85
 struct pyfcgi_stats_shm_s
72 86
 {
87
+	/**@brief Workers count */
73 88
 	int nworker;
89
+	/**@brief Load average */
74 90
 	int pool_load;
75 91
 };
76 92
 
@@ -79,13 +95,14 @@ struct pyfcgi_stats_shm_s
79 95
  * Set an handler for SIGALRM and set a repeating alarm each seconds
80 96
  * @warning designed to be called from monitor server process
81 97
  * @return -1 on error else 0
98
+ * @ingroup stats
82 99
  */
83 100
 int pyfcgi_stats_init();
84 101
 
85 102
 /**@brief SIGALRM signal handler
86
- * @param int signum
103
+ * @param signum
87 104
  */
88
-void pyfcgi_stats_collector(int);
105
+void pyfcgi_stats_collector(int signum);
89 106
 
90 107
 /**@brief Format all stats in a buffer
91 108
  * @note uses the pyfcgi_stats.statsbuff buffer */
@@ -97,33 +114,44 @@ size_t pyfcgi_stats_format();
97 114
 void pyfcgi_stats_buffprintf(const char *fmt, ...);
98 115
 
99 116
 /**@brief Allocate the buffer with at least given space
100
- * @param size_t sz the minimum buffer size
117
+ * @param sz the minimum buffer size
101 118
  * @note allocation size is rounded
102 119
  * @return 0 if OK else -1
103 120
  */
104
-int pyfcgi_stats_reqbuff(size_t);
121
+int pyfcgi_stats_reqbuff(size_t sz);
105 122
 
106 123
 /**@brief Returns statistics about a 900s ringbuffer
107 124
  *
108
- * @param const int[PYFCGI_STATS_SZ] data : a 900 ringbuffer stats samples
109
- * @param int* idx_nxt next data index in ring buffer (allow interrupt
125
+ * @param data a 900 ringbuffer stats samples
126
+ * @param idx_nxt next data index in ring buffer (allow interrupt
110 127
  * detection : when *idx_nxt changes)
111
- * @param int *last : last sample
112
- * @param double[4] avgs : average samples on 1, 5, 10 and 15 minutes
128
+ * @param *last : last sample
129
+ * @param avgs : average samples on 1, 5, 10 and 15 minutes
113 130
  * @return 0 if no error else -1 and set errno to EINTR
114 131
  */
115
-int pyfcgi_stats_avg(const int[PYFCGI_STATS_SZ], int*, int*, double[4]);
132
+int pyfcgi_stats_avg(const int data[PYFCGI_STATS_SZ], int* idx_nxt, int* last,
133
+	double avgs[4]);
116 134
 /**@brief Same than @ref pyfcgi_stats_avg but normalize average when
117 135
  * uptime is bellow 900
118 136
  * @see pyfcgi_stats_avg
137
+ * @param data a 900 ringbuffer stats samples
138
+ * @param idx_nxt next data index in ring buffer (allow interrupt
139
+ * detection : when *idx_nxt changes)
140
+ * @param *last : last sample
141
+ * @param avgs : average samples on 1, 5, 10 and 15 minutes
142
+ * @return 0 if no error else -1 and set errno to EINTR
119 143
  */
120
-int pyfcgi_stats_avg_const(const int[PYFCGI_STATS_SZ], int*, int*, double[4]);
144
+int pyfcgi_stats_avg_const(const int data[PYFCGI_STATS_SZ], int* idx_nxt, int* last,
145
+	double avgs[4]);
121 146
 
122 147
 /**@brief Returns the formated buffer
123 148
  * @todo make @ref pyfcgi_stats_format() implement this functionnality
124 149
  * to remove this function... */
125 150
 const char *pyfcgi_stats_buff(const char **, size_t*);
126 151
 
152
+/**@brief Fetch stats informations from dedicated SHM
153
+ * @see pyfcgi_stats_shm_s
154
+ */
127 155
 int pyfcgi_stats_get_shm(pyfcgi_stats_shm_t*);
128 156
 
129 157
 #endif

+ 8
- 12
src/main.c View File

@@ -17,12 +17,16 @@
17 17
  * along with PyFCGI.  If not, see <http://www.gnu.org/licenses/>.
18 18
  */
19 19
 
20
-/**@defgroup processes Process organisation of PyFCGI
20
+/**@defgroup proc_intern Internal process management
21
+ * @brief Groups all information on internal sub-processes management
22
+ */
23
+/**@defgroup processes PyFCGI process hierarchy
21 24
  *
22 25
  * PyFCGI is organised in three layer : 
23 26
  * A @ref main_proc : simple, that keep running and spawn a
24 27
  * @ref work_master_proc . This process handles @ref worker_process creation
25 28
  * and try to maintain a pool able to reply efficiently to CGI requests.
29
+ * @ingroup proc_intern
26 30
  */
27 31
 /**@defgroup main_proc Main process
28 32
  * @brief The main process in the @ref main() function
@@ -349,14 +353,11 @@ if ($programname contains 'pyfcgi') then {
349 353
 /**@page pyfcgi
350 354
  * @brief Python Fast CGI runner
351 355
  * @section man_syn SYNOPSIS
352
- * spawn-fcgi [OPTS] -- pyfcgi [OPTIONS]
356
+ * pyfcgi [OPTIONS]
353 357
  * @section man_desc DESCRIPTION
354 358
  * Run WSGI python application in a pool of worker.
355 359
  *
356 360
  * @section man_opt OPTIONS
357
- * @subsection man_opt_spawn spawn-fcgi OPTIONS
358
- * OPTS are @ref spawn-fcgi(1) options.
359
- *
360 361
  * @subsection man_opt_gen General OPTIONS
361 362
  * @par -h --help
362 363
  * Display help and exit
@@ -430,13 +431,11 @@ if ($programname contains 'pyfcgi') then {
430 431
  * @section EXAMPLES 
431 432
  * To run foo_pep333.entrypoint() PEP333 application :
432 433
  * 
433
- * spawn-fcgi -d . -n -p 9000 -a 127.0.0.1 -- src/pyfcgi -S
434
- * -e foo_pep333 -E entrypoint
434
+ * src/pyfcgi -l '127.0.0.1:9000' -S -e foo_pep333 -E entrypoint
435 435
  *
436 436
  * Logfile example :
437 437
  *
438
- * spawn-fcgi -d . -n -p 9000 -a 127.0.0.1 -- src/pyfcgi -S
439
- * -e foo_pep333 -E entrypoint
438
+ * src/pyfcgi -l '127.0.0.1:9000' -S -e foo_pep333 -E entrypoint
440 439
  * -L '/tmp/foo.log;0xff;{datetime} {msg} {ident}'
441 440
  *
442 441
  * @section AUTHOR
@@ -449,9 +448,6 @@ if ($programname contains 'pyfcgi') then {
449 448
  * This is free software: you are free to change and redistribute it.
450 449
  * There is NO WARRANTY, to extent permitted by law.
451 450
  *
452
- * @section man_see_also See Also
453
- * @ref spawn-fcgi(1)
454
- *
455 451
  * PyFCGI git repositorie &lt;https://git.yannweb.net/yannweb/pyfcgi>
456 452
  *
457 453
  */

+ 4
- 3
src/python_ioin.c View File

@@ -4,14 +4,15 @@
4 4
  */
5 5
 
6 6
 /**@brief If given object io_stream is NULL set error indicator
7
+ * @param self The IoIn instance
7 8
  * @return 0 if no error else -1 or -2
8 9
  */
9 10
 static int _check_nullin(PyObject *self);
10 11
 
11 12
 /**@brief Request a new buffer size.
12 13
  * 
13
- * @param PyObject* self The IoIn instance
14
- * @param int nreq number of bytes required in buffer
14
+ * @param self The IoIn instance
15
+ * @param nreq number of bytes required in buffer
15 16
  * @return 0 on error else buffer size
16 17
  */
17 18
 static int pyfcgi_io__reqbuf(PyObject *self, int nreq);
@@ -698,7 +699,7 @@ static int pyfcgi_io__reqbuf(PyObject *self, int nreq)
698 699
 }
699 700
 
700 701
 /**@brief Concat two bytes/unicode given IoIn configuration flag
701
- * @warn Py_DECREF both arguments
702
+ * @warning Py_DECREF both arguments
702 703
  */
703 704
 static PyObject* IoIn__Concat(PyObject *self, PyObject *left, PyObject *right)
704 705
 {

+ 3
- 3
src/pyworker.c View File

@@ -29,10 +29,10 @@ static inline void worker_set_idle();
29 29
 static inline void worker_set_busy();
30 30
 
31 31
 /**@brief Process results from a pep333 worker
32
- * @param FCGX_Stream* out stream from libFCGI
33
- * @param PyObject* application function returned value
32
+ * @param out out stream from libFCGI
33
+ * @param ret application function returned value
34 34
  */
35
-static inline int work333_send_result(FCGX_Stream*, PyObject* ret);
35
+static inline int work333_send_result(FCGX_Stream* out, PyObject* ret);
36 36
 
37 37
 
38 38
 static int worker_piper_sigrcv = 0;

Loading…
Cancel
Save