Reviewed-by: Steven Dake <sdake@xxxxxxxxxx> On 10/21/2011 12:57 AM, Angus Salkeld wrote: > Signed-off-by: Angus Salkeld <asalkeld@xxxxxxxxxx> > --- > TODO | 2 - > man/coroipc_overview.8 | 177 ------------------------------------------ > man/logsys_overview.8 | 201 ------------------------------------------------ > 3 files changed, 0 insertions(+), 380 deletions(-) > delete mode 100644 man/coroipc_overview.8 > delete mode 100644 man/logsys_overview.8 > > diff --git a/TODO b/TODO > index fa30e36..d19edbd 100644 > --- a/TODO > +++ b/TODO > @@ -17,8 +17,6 @@ master > > 3) is this https://github.com/asalkeld/libqb/issues/1 still an issue? > > -4) remove "old" stuff from the man pages (logging/IPC). > - > 5) new blackbox size might be too small (exec/logsys.c:311) > > 6) extend the logging config to make better use of the tracing capabilities. > diff --git a/man/coroipc_overview.8 b/man/coroipc_overview.8 > deleted file mode 100644 > index 8912f90..0000000 > --- a/man/coroipc_overview.8 > +++ /dev/null > @@ -1,177 +0,0 @@ > -.\"/* > -.\" * Copyright (c) 2009 Red Hat, Inc. > -.\" * > -.\" * All rights reserved. > -.\" * > -.\" * Author: Steven Dake (sdake@xxxxxxxxxx) > -.\" * > -.\" * This software licensed under BSD license, the text of which follows: > -.\" * > -.\" * Redistribution and use in source and binary forms, with or without > -.\" * modification, are permitted provided that the following conditions are met: > -.\" * > -.\" * - Redistributions of source code must retain the above copyright notice, > -.\" * this list of conditions and the following disclaimer. > -.\" * - Redistributions in binary form must reproduce the above copyright notice, > -.\" * this list of conditions and the following disclaimer in the documentation > -.\" * and/or other materials provided with the distribution. > -.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its > -.\" * contributors may be used to endorse or promote products derived from this > -.\" * software without specific prior written permission. > -.\" * > -.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" > -.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE > -.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE > -.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE > -.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR > -.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF > -.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS > -.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN > -.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) > -.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF > -.\" * THE POSSIBILITY OF SUCH DAMAGE. > -.\" */ > -.TH COROIPC_OVERVIEW 8 2009-03-21 "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" > -.SH NAME > -coroipc_overview \- Overview of coroipc libraries > -.SH OVERVIEW > -The coroipcs and coroipcc libraries provide a generically reusable very high > -performance shared memory IPC sytem for client and service applications. > -It supports many features including: > -.PP > -65536 user services and 65536 command ids per service. > -.PP > -Shared memory implementation for very high performance. > -.PP > -A synchronous request/response channel and asynchronous response channel > -per ipc connection. > -.PP > -User defined private data per IPC connection. > -.PP > -Ability to call a function per service on ipc connection and disconnection. > -.PP > -Authenticated IPC connection with ability for developer to define which > -UIDs and GIDs are valid at connection time. > -.PP > -Fully abstracted poll system so that any poll library may be used. > -.PP > -User defined selector for determining the proper function to call per > -service and id. > - > -.SH Description of the libraries > -There are two shared libraries available for developing IPC client applications. > - > -The first library is coroipcs.so which is responsible for the server > -implementation. This library should be linked with the server and then > -initialized with coroipcs_init(3). > - > -Once the library is initialized, it will provide service to coroipcc.so library > -users. > - > -The second library is coroipcc.so which is responsible for the client > -implementation. This library should be linked with the client and requires > -no initialization. This library provides communication functions for sending > -and receiving synchronous requests, and also reading asynchronous message > -requests from the server. > - > -.SH Initializing the coroipcs library > -To use the coroipcs library, the developer creates a coroipcs_init_state > -structure and populates it with function names. The functions do various > -operations described in coroipcs_init(3) man page. Not all operations must > -be specified. If some are missing, the corosync ipcs library will > -automatically populate the structure with internal versions which provide > -basic functionality. > - > -.SH Communicating with the coroipcc clients > -Every ipc connection is represented by a void * pointer which uniquely > -identifies the data set for the IPC connection. Each IPC connection also > -contains user defined private data. To obtain this private data pointer, the > -function coroipcs_private_data_get(3) function can be called. > - > -There are two channels for communication. The primary channel is the > -synchronous request/response channel. Another channel is available for out of > -band asynchronous responses from the server. > - > -To send a response on the syncronous channel, coroipcs_response_send(3) or > -coroipcs_response_iov_send(3) should be used. To send a message on the > -asynchronous channel, coroipcs_dispatch_send(3) or coroipc_dispatch_iov_send(3) > -should be used. > - > -.SH The abstracted poll system > -There are many different poll systems in use in applications. They are usually > -intricately tied up in the implementation of the application and each provide > -different APIs and functionality. To manage this, the coroipcs library > -provides callbacks in coroipcs_init(3) which should be called when a new > -connection should be added for accept system calls or to dispatch messages. > - > -These callbacks add the relevant fd to the application's poll system. When the > -application poll system triggers the callback registered by the user defined > -poll adding functions, they then call either coroipc_handler_accept(3) or > -coroipc_handler_dispatch(3). > - > -.SH Initializing the coroipcc library > -No initialization is required in the coroipcc library. > - > -.SH Lifecycle of an IPC connection. > -An IPC connection is made to the server with coroipcc_service_connect(3). This > -function connects to the server and requests channels be created for > -communication. To disconnect, the client either exits or executes the > -function coroipcc_service_disconnect(3). > - > -.SH Synchronous communication > -There are two functions for sending a request and receiving a response. The > -first function coroipcc_msg_send_reply_receive(3) sends an iovector request > -and receives a response. This function copies the response into the response > -buffer. the second function coroipcc_msg_end_reply_receive_in_buf(3) does not > -copy the response buffer and allows for zero-copy reading of the response > -when the lifetime of the response buffer is known. > - > -.SH Asynchronous communication > -The coroipcc_dispatch_recv(3) function receives an out-of-band asyncronous > -message. Unlike the synchronous communication channel, the asynchronous > -messages are queued and can provide very high out-of-band performance. > - > -To determine when to call coroipcc_dispatch_recv(3) the corosync_fd_get(3) call > -is used to obtain a file descriptor used in the poll(2) or select(2) system > -calls. > - > -Finally the current dispatch flow control state can be obtained with > -coroipcc_flow_control_get(3). > - > -.SH Performance > -The ipc system is tuned for very high performance while also being comletely > -abstracted from the underlying poll mechanism and any internalisms required > -by the server. The ipc system achieves such high performance by using shared > -memory as oppossed to slower techniques such as UNIX_PF sockets. > - > -We intend to do further development to allow syncronous requests to return > -messages in an asyncronous way to avoid blocking involved in the syncronous > -request/response model used today for higher throughput in some use cases. > - > -.SH Security > -The ipc system uses default operating system security mechanics to ensure > -ipc connections are validated. A callback used with coroipcs_init(3) is called > -for every new ipc connection with the parameters of UID and GID. The callback > -then determines if the UID and GID are authenticated for communication. More > -about this topic can be viewed in the coroipcs_init(3) man page. > - > -.SH "SEE ALSO" > -.BR coroipcs_ipc_init (3), > -.BR coroipcs_ipc_exit (3), > -.BR coroipcs_private_data_get (3), > -.BR coroipcs_respone_send (3), > -.BR coroipcs_response_iov_send (3), > -.BR coroipcs_dispatch_send (3), > -.BR coroipcs_dispatch_iov_send (3), > -.BR coroipcs_refcount_inc (3), > -.BR coroipcs_refcount_dec (3), > -.BR coroipcs_handler_accept (3), > -.BR coroipcs_handler_dispatch (3), > - > -.BR cooripcc_service_connect (3), > -.BR coroipcc_service_disconnect (3), > -.BR coroipcc_msg_send_reply_receive (3), > -.BR coroipcc_msg_send_reply_receive_in_buf (3), > -.BR coroipcc_dispatch_recv (3), > -.BR coroipcc_fd_get(3), > -.BR coroipcc_dispatch_flow_control_get (3) > diff --git a/man/logsys_overview.8 b/man/logsys_overview.8 > deleted file mode 100644 > index fb2a26a..0000000 > --- a/man/logsys_overview.8 > +++ /dev/null > @@ -1,201 +0,0 @@ > -.\"/* > -.\" * Copyright (c) 2007-2009 Red Hat, Inc. > -.\" * > -.\" * All rights reserved. > -.\" * > -.\" * Author: Steven Dake (sdake@xxxxxxxxxx) > -.\" * Author: Fabio M. Di Nitto (fdinitto@xxxxxxxxxx) > -.\" * > -.\" * This software licensed under BSD license, the text of which follows: > -.\" * > -.\" * Redistribution and use in source and binary forms, with or without > -.\" * modification, are permitted provided that the following conditions are met: > -.\" * > -.\" * - Redistributions of source code must retain the above copyright notice, > -.\" * this list of conditions and the following disclaimer. > -.\" * - Redistributions in binary form must reproduce the above copyright notice, > -.\" * this list of conditions and the following disclaimer in the documentation > -.\" * and/or other materials provided with the distribution. > -.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its > -.\" * contributors may be used to endorse or promote products derived from this > -.\" * software without specific prior written permission. > -.\" * > -.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" > -.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE > -.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE > -.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE > -.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR > -.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF > -.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS > -.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN > -.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) > -.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF > -.\" * THE POSSIBILITY OF SUCH DAMAGE. > -.\" */ > -.TH QB_LOGSYS_OVERVIEW 8 2009-06-16 "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" > -.SH NAME > -logsys_overview \- Logsys Library Overview > -.SH OVERVIEW > -The logsys library provides a generically usable logging and tracing system for > -use by applications. It supports many features including: > -.PP > -Configurable subsystem logging or single system logging > -.PP > -Threaded non-blocking logging of log output data for better non-blocking performance > -.PP > -Support for 8 tracing levels and tracing the entering and leaving of functions > -.PP > -Declaration of logging system or subsystem without calling any functions > -.PP > -Dynamic reconfiguration of the logging system parameters > -.PP > -Logging to syslog, file, stderr. > - > -.SH Declaration of the System logger > -The logsys library is initially configured by including logsys.h and declaring > -a logger. Once the logger is declared, optional subsystem loggers can be > -declared in every file. > - > -The definition QB_LOGSYS_DECLARE_SYSTEM is placed after the include section of one > -C file in the application. This declaration creates a constructor function > -which will be called automatically before main() is executed. This technique > -avoids the need for calling any setup functions in short applications that don't > -require it and enables full logging capabilities before any application code is > -executed. > - > -#define QB_LOGSYS_DECLARE_SYSTEM (name, mode, debug, file, file_priority, > -syslog_facility, syslog_priority, format, fltsize) > - > -The name parameter is the name of the application or system. > - > -The mode parameter is the logging mode of the system. > -The following modes can be configured by logically ORing these flags: > - > -QB_LOGSYS_MODE_OUTPUT_FILE: Output all log data to the file parameter of this declaration > - > -QB_LOGSYS_MODE_OUTPUT_STDERR: Output all log data to the stderr descriptor > - > -QB_LOGSYS_MODE_OUTPUT_SYSLOG: Output all log data to syslog using a non-blocking thread > - > -QB_LOGSYS_MODE_FORK: This flags tells logsys to queue all data untill the application > -has forked. The application is then responsible to call logsys_fork_completed to flush > -the queue and start logging. > - > -QB_LOGSYS_MODE_THREADED: Starts a separate thread to handle non-blocking logging operations. > -If this flag is not specified, the logging operations are blocking. > - > -The debug parameter, if enabled, turns off all messages priority filtering, recording > -everything everywhere. > - > -The file parameter specifies the filename that should be used to log messages. > -This parameter may be NULL and no log file will be created. > - > -The file_priority parameter specifies the message priority that should be logged to file. > - > -The syslog_facility parameter is the syslog facility that should be used when logging > -messages. > - > -The syslog_priority, similar to file_priority, specifies the message priority that should be logged to > -syslog. > - > -The format parameter allows to set custom output format. > -Set to NULL to use built-in default. > - > -The fltsize parameter specifies the flight recorder buffer size in bytes. The requested value > -is increased by the size of 2 unsigned ints and rounded to the next PAGE_SIZE. > - > -An example declaration would be: > - > -#include <corosync/logsys.h> > - > -... (other #includes) > - > -QB_LOGSYS_DECLARE_SYSTEM ("test", /* name */ > - QB_LOGSYS_MODE_OUTPUT_STDERR | QB_LOGSYS_MODE_THREADED, /* mode */ > - 0, /* debug */ > - NULL, /* logfile path */ > - QB_LOGSYS_LEVEL_INFO, /* logfile_priority */ > - LOG_DAEMON, /* syslog facility */ > - QB_LOGSYS_LEVEL_INFO, /* syslog level */ > - NULL, /* use default format */ > - 1000000); /* flight recorder size */ > - > - > -.SH Declaration of subsystems > -The logsys library supports the logging of information to one main system or > -subsystem. This is specified in each individual object C file in the system > -and it is entirely optional. > - > -An example: > - > -QB_LOGSYS_DECLARE_SUBSYS ("subsystest"); > - > -It is possible to use the same subsystem name in separate object files. > -In this case, the individual logging parameters for those subsystem identifier > -will be used. > - > -A newly created subsystem inherits the system configuration at the time of > -creation. > - > -It is possible to override every configuration option on a subsystem base > -throught the configuration API. > - > -.SH Logging Messages > -The definition log_printf is used to log information to the log. It works > -in a similiar fashion to printf, except it has a first parameter of level > -which may be the following: > -QB_LOGSYS_LEVEL_EMERG > -QB_LOGSYS_LEVEL_ALERT > -QB_LOGSYS_LEVEL_CRIT > -QB_LOGSYS_LEVEL_ERR > -QB_LOGSYS_LEVEL_WARNING > -QB_LOGSYS_LEVEL_NOTICE > -QB_LOGSYS_LEVEL_INFO > -QB_LOGSYS_LEVEL_DEBUG > - > -An example of using log_printf would be > - > -log_printf (QB_LOGSYS_LEVEL_EMERG, "This is an emergency %s value %d\n", string, value); > - > -Tracing of functions can be done using ENTER(), LEAVE(); > - > -An example of using ENTER is > -void function (char *name) { > -ENTER(); > -... function contents ... > -LEAVE(); > -} > - > -Individual tracing levels are supported through the macros > -TRACE1(format, args) > -TRACE2(format, args) > -.. > -TRACE8(format, args) > - > -An example of using TRACE is > - > -char *name = "test"; > -TRACE7 ("This is a trace 7 log with name %s\n", name); > - > -Note that ENTER/LEAVE/TRACE* calls are recorded only in the flight recorder. > - > -.SH "SEE ALSO" > -.BR logsys_fork_completed (3), > -.BR logsys_atexit (3), > -.BR logsys_log_rec_store (3), > -.BR logsys_format_set (3), > -.BR logsys_format_get (3), > -.BR logsys_config_mode_set (3), > -.BR logsys_config_file_set (3), > -.BR logsys_config_syslog_facility_set (3), > -.BR logsys_config_syslog_facility_get (3), > -.BR logsys_config_mode_set (3), > -.BR logsys_config_mode_get (3), > -.BR logsys_config_file_set (3), > -.BR logsys_config_logfile_priority_set (3), > -.BR logsys_config_debug_set (3), > -.BR logsys_facility_id_get (3), > -.BR logsys_facility_name_get (3), > -.BR logsys_priority_id_get (3), > -.BR logsys_priority_name_get (3), > -.PP _______________________________________________ discuss mailing list discuss@xxxxxxxxxxxx http://lists.corosync.org/mailman/listinfo/discuss
