From 6c8a8808ff730e085c7780eb4154955927f96564 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Pokorn=C3=BD?= Date: Wed, 21 Jun 2017 19:42:44 +0200 Subject: [PATCH 1/7] Fix typo: p{rr -> r}ocess MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jan Pokorný --- include/qb/qbrb.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/qb/qbrb.h b/include/qb/qbrb.h index 972d66005..7e4d897fe 100644 --- a/include/qb/qbrb.h +++ b/include/qb/qbrb.h @@ -40,7 +40,7 @@ extern "C" { * is full. * * This implementation is capable of working across processes, but one process - * must only write and the other prrocess read. + * must only write and the other process read. * * The read process will do the following: * @code From 7090874ab9aec56744545afeebd514bf6f7b0ef4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Pokorn=C3=BD?= Date: Thu, 29 Jun 2017 18:23:52 +0200 Subject: [PATCH 2/7] doc: qbrb.h: several fixes to punctuation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jan Pokorný --- include/qb/qbrb.h | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/include/qb/qbrb.h b/include/qb/qbrb.h index 7e4d897fe..622587300 100644 --- a/include/qb/qbrb.h +++ b/include/qb/qbrb.h @@ -32,9 +32,9 @@ extern "C" { /** * @file qbrb.h - * This implements a ring buffer that works in "chunks" not bytes. + * This implements a ring buffer that works in "chunks", not bytes. * So you write/read a complete chunk or not at all. - * There are two types of ring buffer normal and overwrite. + * There are two types of ring buffer: normal and overwrite. * Overwrite will reclaim the oldest chunks inorder to make way for new ones, * the normal version will refuse to write a new chunk if the ring buffer * is full. @@ -75,7 +75,7 @@ extern "C" { */ /** - * create a ring buffer (rather than open and existing one) + * Create a ring buffer (rather than open and existing one). * @see qb_rb_open() */ #define QB_RB_FLAG_CREATE 0x01 @@ -126,7 +126,7 @@ qb_ringbuffer_t *qb_rb_open(const char *name, size_t size, uint32_t flags, size_t shared_user_data_size); /** - * Dereference the ringbuffer and if we are the last user destroy it. + * Dereference the ringbuffer and, if we are the last user, destroy it. * * All files, mmaped memory, semaphores and locks will be destroyed. * @@ -184,7 +184,7 @@ ssize_t qb_rb_chunk_write(qb_ringbuffer_t * rb, const void *data, size_t len); void *qb_rb_chunk_alloc(qb_ringbuffer_t * rb, size_t len); /** - * finalize the chunk. + * Finalize the chunk. * @param rb ringbuffer instance * @param len (in) the size of the chunk. */ @@ -277,7 +277,7 @@ ssize_t qb_rb_write_to_file(qb_ringbuffer_t * rb, int32_t fd); qb_ringbuffer_t *qb_rb_create_from_file(int32_t fd, uint32_t flags); /** - * Like 'chown' it changes the owner and group of the ringbuffers + * Like 'chown', it changes the owner and group of the ringbuffer's * resources. * @param owner uid of the owner to change to * @param group gid of the group to change to @@ -287,7 +287,7 @@ qb_ringbuffer_t *qb_rb_create_from_file(int32_t fd, uint32_t flags); int32_t qb_rb_chown(qb_ringbuffer_t * rb, uid_t owner, gid_t group); /** - * Like 'chmod' it changes the mode of the ringbuffers resources. + * Like 'chmod', it changes the mode of the ringbuffer's resources. * @param mode mode to change to * @param rb ringbuffer instance * @retval 0 == ok From e1e71cf67770f53651fc793a6ef374f7a5ef1cc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Pokorn=C3=BD?= Date: Thu, 29 Jun 2017 18:25:51 +0200 Subject: [PATCH 3/7] doc: qbrb.h: reindent example writer's error label as per reader MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jan Pokorný --- include/qb/qbrb.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/qb/qbrb.h b/include/qb/qbrb.h index 622587300..6a51d7308 100644 --- a/include/qb/qbrb.h +++ b/include/qb/qbrb.h @@ -46,7 +46,7 @@ extern "C" { * @code * rb = qb_rb_open("test2", 2000, QB_RB_FLAG_SHARED_PROCESS|QB_RB_FLAG_CREATE); * for (i = 0; i < 200; i++) { - * try_read_again: + * try_read_again: * l = qb_rb_chunk_read(rb, (void *)out, 32, 1000); * if (l < 0) { * goto try_read_again; From ab995c1c8813d613ec7beb93a9340c6f85820129 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Pokorn=C3=BD?= Date: Wed, 21 Jun 2017 19:41:30 +0200 Subject: [PATCH 4/7] doc: qbhdb.h: explain former importance to libqb itself MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jan Pokorný --- include/qb/qbhdb.h | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/include/qb/qbhdb.h b/include/qb/qbhdb.h index 846b5180a..25fc9a453 100644 --- a/include/qb/qbhdb.h +++ b/include/qb/qbhdb.h @@ -39,6 +39,11 @@ extern "C" { /** * @file qbhdb.h * The handle database is for reference counting objects. + * + * @note + * Historically, handle database implementation also served internal needs + * of libqb (e.g. for IPC services tracking), which was eventually replaced + * with indirection-less reference counters and their direct modifications. */ /** From 713c8bbd330dbdb52c05576e23b3fc45a6262bd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Pokorn=C3=BD?= Date: Thu, 29 Jun 2017 17:01:41 +0200 Subject: [PATCH 5/7] doc: ipcc.c: explain why client would timebox recv from server MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also refer to commit d633b4e. Signed-off-by: Jan Pokorný --- lib/ipcc.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/ipcc.c b/lib/ipcc.c index 5c9032272..e29209559 100644 --- a/lib/ipcc.c +++ b/lib/ipcc.c @@ -323,6 +323,8 @@ qb_ipcc_sendv_recv(qb_ipcc_connection_t * c, } do { + /* following is a liveness-driven interleaving + (for cases the server side failed/exited) */ if (timeout_rem > QB_IPC_MAX_WAIT_MS || ms_timeout == -1) { timeout_now = QB_IPC_MAX_WAIT_MS; } else { From 70671456fe288ff1936c189d947575e95d83b7fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Pokorn=C3=BD?= Date: Thu, 20 Jul 2017 14:32:58 +0200 Subject: [PATCH 6/7] doc: qblog.h: minor stylistic/doxygen markup cosmetics MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jan Pokorný --- include/qb/qblog.h | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/include/qb/qblog.h b/include/qb/qblog.h index 01efdd5c5..d7ca48de5 100644 --- a/include/qb/qblog.h +++ b/include/qb/qblog.h @@ -535,7 +535,7 @@ void qb_log_callsites_dump(void); * * @param target QB_LOG_SYSLOG, QB_LOG_STDERR or result from qb_log_file_open() * @param conf_type configuration directive ("what to configure") that accepts - * int32_t argument determining the new value unless ignored + * @c int32_t argument determining the new value unless ignored * for particular directive altogether * (incompatible directives: QB_LOG_CONF_IDENT) * @param arg the new value for a state-changing configuration directive, @@ -558,7 +558,7 @@ typedef union { * * @param target QB_LOG_SYSLOG, QB_LOG_STDERR or result from qb_log_file_open() * @param conf_type configuration directive ("what to configure") that accepts - * either int32_t or a null-terminated string argument + * either @c int32_t or a null-terminated string argument * determining the new value unless ignored for particular directive * (compatible directives: those valid for qb_log_ctl * + QB_LOG_CONF_IDENT) @@ -569,9 +569,9 @@ typedef union { * that original function directly as it allows for more type safety) * @see qb_log_ctl * - * @note You can use QB_LOG_CTL2_I32 and QB_LOG_CTL2_S - * macros for a convenient on-the-fly construction of the object - * to be passed as an arg argument. + * @note You can use @ref QB_LOG_CTL2_I32 and @ref QB_LOG_CTL2_S macros + * for a convenient on-the-fly construction of the object + * to be passed as an @p arg argument. */ int32_t qb_log_ctl2(int32_t target, enum qb_log_conf conf_type, qb_log_ctl2_arg_t arg); @@ -640,7 +640,7 @@ void qb_log_tags_stringify_fn_set(qb_log_tags_stringify_fn fn); * %P PID * %H hostname * - * any number between % and character specify field length to pad or chop + * Any number between % and character specify field length to pad or chop. */ void qb_log_format_set(int32_t t, const char* format); @@ -707,13 +707,13 @@ void qb_log_custom_close(int32_t t); void *qb_log_target_user_data_get(int32_t t); /** - * Associate user data with this log target + * Associate user data with this log target. * @note only use this with custom targets */ int32_t qb_log_target_user_data_set(int32_t t, void *user_data); /** - * format the callsite and timestamp info according to the format + * Format the callsite and timestamp info according to the format. * set using qb_log_format_set() * It is intended to be used from your custom logger function. */ From ab8d4dbf9394cf2b5eeeae6725dc4112587dc2d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Pokorn=C3=BD?= Date: Thu, 20 Jul 2017 14:35:33 +0200 Subject: [PATCH 7/7] doc: qblog.h: note qb_log_format_set vs. fork interaction wrt. PIDs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jan Pokorný --- include/qb/qblog.h | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/include/qb/qblog.h b/include/qb/qblog.h index d7ca48de5..3cb4eef86 100644 --- a/include/qb/qblog.h +++ b/include/qb/qblog.h @@ -641,6 +641,14 @@ void qb_log_tags_stringify_fn_set(qb_log_tags_stringify_fn fn); * %H hostname * * Any number between % and character specify field length to pad or chop. + * + * @note Some of the fields are immediately evaluated and remembered + * for performance reasons, so when there's an objective for log + * messages to carry PIDs (not in the default setup) and, moreover, + * precisely, this function needs to be reinvoked upon @c fork + * (@c clone) in the respective children. When already linking + * to @c libpthread, @c pthread_atfork callback registration + * could be useful. */ void qb_log_format_set(int32_t t, const char* format);