NCBI C++ ToolKit
ncbi_c_log.h
Go to the documentation of this file.

Go to the SVN repository for this file.

00001 #ifndef NCBI_C_LOG__H
00002 #define NCBI_C_LOG__H
00003 
00004 /* $Id: ncbi_c_log.h 63756 2014-07-23 14:13:21Z ivanov $
00005  * ===========================================================================
00006  *
00007  *                            PUBLIC DOMAIN NOTICE
00008  *               National Center for Biotechnology Information
00009  *
00010  *  This software/database is a "United States Government Work" under the
00011  *  terms of the United States Copyright Act.  It was written as part of
00012  *  the author's official duties as a United States Government employee and
00013  *  thus cannot be copyrighted.  This software/database is freely available
00014  *  to the public for use. The National Library of Medicine and the U.S.
00015  *  Government have not placed any restriction on its use or reproduction.
00016  *
00017  *  Although all reasonable efforts have been taken to ensure the accuracy
00018  *  and reliability of the software and data, the NLM and the U.S.
00019  *  Government do not and cannot warrant the performance or results that
00020  *  may be obtained by using this software or data. The NLM and the U.S.
00021  *  Government disclaim all warranties, express or implied, including
00022  *  warranties of performance, merchantability or fitness for any particular
00023  *  purpose.
00024  *
00025  *  Please cite the author in any work or product based on this material.
00026  *
00027  * ===========================================================================
00028  *
00029  * Author:  Vladimir Ivanov
00030  *
00031  * @file
00032  * File Description:
00033  *    The C library to provide C++ Toolkit-like logging semantics 
00034  *    and output for C/C++ programs and CGIs.
00035  *
00036  * The C Logging API have two usage patterns:
00037  *
00038  *   1) First (recommended) method.
00039  *      Usage:
00040  *      - At the program start call NcbiLog_Init() (or MT/ST version),
00041  *        only once, probably from the main thread.
00042  *      - Call any logging methods.
00043  *      - For each application's thread that have used the C Logging API 
00044  *        call NcbiLog_Destroy_Thread() before thread termination.
00045  *      - After using API, or before program's exit call NcbiLog_Destroy().
00046  *
00047  *   2) Second method should be used only in special cases, where impossible
00048  *      to call NcbiLog_Init/NcbiLog_Destroy. Any of these two methods still 
00049  *      can be used...  But, if you can call both of them, consider to use
00050  *      pattern (1) instead. Forgot about NcbiLog_Destroy_Thread(), don't
00051  *      use it at all. And aware, that default MT locking implementation
00052  *      will be used automatically in MT configurations if you didn't use
00053  *      NcbiLog_Init() with your own MT-handler explicitly.
00054  *      Usage:
00055  *      - First, if you didn't call NcbiLog_Init() yet, you can call
00056  *        NcbiLog_InitForAttachedContext(). It does the same initializations
00057  *        as NcbiLog_Init(), but have better MT protection, and can be called
00058  *        as many times as you want, even in any thread. And even this step
00059  *        can be skipped, and all initialization will be done in 
00060  *        NcbiLog_Context_Create(). But you still have a possibility to pass
00061  *        an application name into the logging API. Only first call of 
00062  *        NcbiLog_Init*() have effect. All subsequent calls will be ignored.
00063  *      - Call NcbiLog_Context_Create() to create thread-specific contex.
00064  *      - Use NcbiLog_Context_Attach() to attach created context to the API.
00065  *      - Call any logging methods. Do not call them before attaching context,
00066  *        or you can get memory/resource leaks and unpredictable results.
00067  *      - Detach context with NcbiLog_Context_Detach().
00068  *        The pairs of NcbiLog_Context_Attach/NcbiLog_Context_Detach methods
00069  *        can be used as many times as needed. The thread-specific context
00070  *        should be saved somewhere between logging sessions. 
00071  *      - Use NcbiLog_Context_Destroy() when logging is done and you don't
00072  *        need a logging context object anymore.
00073  *      - Call NcbiLog_Destroy() to shutdown API. Do this only if possible.
00074  *        This step is recommended, and can help to avoid memory leaks.
00075  *
00076  * Any C logging API functions can be called only after first call of
00077  * NcbiLog_Init*() or NcbiLog_Context_Create(), otherwise its call
00078  * will be ignored.
00079  *
00080  * This library calls assert() when presented with unexpected
00081  * input or other error situations. In Release modes such errors can just
00082  * stop a logging, without aborting a program (except some critical cases).
00083  * But generally, very little graceful error recovery is attempted; that 
00084  * burden is pushed back to the caller.
00085  *
00086  * By default the module is dependent on the /etc/toolkitrc file in order to
00087  * determine which applications should log to which /log sub-directory. 
00088  * If this file can't be found or can't be read, or the log files can not
00089  * be open, it fall back to logging to destination specified here:
00090  * http://www.ncbi.nlm.nih.gov/books/NBK7185/#ch_core.Where_Diagnostic_Messages_Go
00091  *
00092  * Thread-specific serial number is always 0. We cannot provide mechanism
00093  * to maintain correct value for each thread.
00094  *
00095  */
00096 
00097 #include <time.h>
00098 
00099 
00100 /** @addtogroup Diagnostics
00101  *
00102  * @{
00103  */
00104 
00105 #if defined(_MSC_VER)
00106 #  if !defined(NCBI_OS_MSWIN)
00107 #    define NCBI_OS_MSWIN  1
00108 #  endif
00109 #else
00110 #  if !defined(NCBI_OS_UNIX)
00111 #    define NCBI_OS_UNIX   1
00112 #  endif
00113 #endif
00114 
00115 #if defined(NCBI_OS_UNIX)
00116 #  ifndef   __STDC_FORMAT_MACROS
00117 #    define __STDC_FORMAT_MACROS
00118 #  endif
00119 #  include <inttypes.h>
00120 #  include <sys/types.h>
00121 #elif defined(NCBI_OS_MSWIN)
00122 #endif
00123 
00124 
00125 #ifdef __cplusplus
00126 extern "C" {
00127 #endif
00128 
00129 
00130 
00131 /******************************************************************************
00132  *  MT locking
00133  */
00134 
00135 /** Lock handle -- keeps all data needed for the locking and the cleanup.
00136  */
00137 struct         TNcbiLog_MTLock_tag;
00138 typedef struct TNcbiLog_MTLock_tag*  TNcbiLog_MTLock;
00139 
00140 
00141 /** The action passed to user defined MT lock handler.
00142  */
00143 typedef enum {
00144     eNcbiLog_MT_Init,          /**< Init the locker (call first)    */
00145     eNcbiLog_MT_Lock,          /**< Lock                            */
00146     eNcbiLog_MT_Unlock,        /**< Unlock                          */
00147     eNcbiLog_MT_Destroy        /**< Unlock and cleanup (call last)  */
00148 } ENcbiLog_MTLock_Action;
00149 
00150 
00151 /** Type of ownership for MT lock handle.
00152  */
00153 typedef enum {
00154     eNcbiLog_MT_NoOwnership,   /**< No ownership relationship */
00155     eNcbiLog_MT_TakeOwnership  /**< NcbiLog API takes ownership of MT lock */
00156 } ENcbiLog_MTLock_Ownership;
00157 
00158 
00159 /** MT locking callback.
00160  *
00161  *  @param user_data
00162  *    See "user_data" in NcbiLog_MTLock_Create()
00163  *  @param action
00164  *    Operation that should be done in the callback handler.
00165  *  @return
00166  *    Non-zero value if the requested operation was successful.
00167  *  @note
00168  *    The "-1" value is reserved for unset handler;  you also
00169  *    may want to return "-1" if your locking function does no locking, and
00170  *    you don't consider it as an error, but still want the caller to be
00171  *    ware of this "rightful non-doing" as opposed to the "rightful doing".
00172  * @sa
00173  *    NcbiLog_MTLock_Create, NcbiLog_MTLock_Delete
00174  */
00175 typedef int/*bool*/ (*FNcbiLog_MTLock_Handler)
00176     (void*                  user_data,
00177      ENcbiLog_MTLock_Action action
00178      );
00179 
00180 
00181 /** Create new MT lock.
00182  *
00183  *  @param user_data
00184  *    Unspecified data to call "handler" with
00185  *  @param handler
00186  *    Locking callback
00187  *  @return
00188  *    Handle to newly created MT lock object or NULL on error.
00189  *  @sa
00190  *    NcbiLog_MTLock_Delete, FNcbiLog_MTLock_Handler
00191  */
00192 extern TNcbiLog_MTLock NcbiLog_MTLock_Create
00193     (void*                   user_data,
00194      FNcbiLog_MTLock_Handler handler
00195      );
00196 
00197 
00198 /** Call cleanup action on the handler, then destroy it.
00199  *
00200  *  @param lock
00201  *    A handle previously obtained from NcbiLog_MTLock_Create().
00202  *  @sa
00203  *    NcbiLog_MTLock_Create, FNcbiLog_MTLock_Handler
00204  */
00205 extern void NcbiLog_MTLock_Delete(TNcbiLog_MTLock lock);
00206 
00207 
00208 /** Default implementation of simple MT locking callback.
00209  *
00210  *  @param user_data
00211  *    Simple handler don't use this parameter; will be ignored.
00212  *  @param action
00213  *    Operation that should be done in the callback handler.
00214  *  @return
00215  *    Non-zero value if the requested operation was successful.
00216  *  @sa
00217  *    FNcbiLog_MTLock_Handler, NcbiLog_MTLock_Create
00218  */
00219 extern int/*bool*/ NcbiLog_Default_MTLock_Handler
00220     (void*                  user_data, 
00221      ENcbiLog_MTLock_Action action
00222      );
00223 
00224 
00225 
00226 /******************************************************************************
00227  *  Common types and definitions
00228  */
00229 
00230 /** Where to write the application's diagnostics to.
00231  *  @sa NcbiLog_SetDestination
00232  */
00233 typedef enum {
00234     eNcbiLog_Default,         /**< Try /log/<*>/<appname>.log; fallback
00235                                    to STDERR */
00236     eNcbiLog_Stdlog,          /**< Try /log/<*>/<appname>.log;  fallback
00237                                    to ./<appname>.log, then to STDERR */
00238     eNcbiLog_Cwd,             /**< Try ./<appname>.log, fallback to STDERR */
00239     eNcbiLog_Stdout,          /**< To standard output stream */
00240     eNcbiLog_Stderr,          /**< To standard error stream  */
00241     eNcbiLog_Disable          /**< Don't write it anywhere   */
00242 } ENcbiLog_Destination;
00243 
00244 
00245 /** Severity level for the posted diagnostics
00246  */
00247 typedef enum {
00248     eNcbiLog_Trace = 0,       /**< Trace message          */
00249     eNcbiLog_Info,            /**< Informational message  */
00250     eNcbiLog_Warning,         /**< Warning message        */
00251     eNcbiLog_Error,           /**< Error message          */
00252     eNcbiLog_Critical,        /**< Critical error message */
00253     eNcbiLog_Fatal            /**< Fatal error -- guarantees exit (or abort) */
00254 } ENcbiLog_Severity;
00255 
00256 
00257 /** Structure to describe pairs 'key=value', used to posting parameters.
00258  *
00259  *  @sa NciLog_ReqStart, NcbiLog_Extra, NcbiLog_Perf
00260  */
00261 typedef struct {
00262     const char* key;
00263     const char* value;
00264 } SNcbiLog_Param;
00265 
00266 
00267 /** Big integer type
00268 */
00269 #if defined(__MINGW32__)  ||  defined(__MINGW64__)
00270    typedef          long long TNcbiLog_Int8;
00271    typedef unsigned long long TNcbiLog_UInt8;
00272 #  define NCBILOG_INT8_FORMAT_SPEC "I64u"
00273 #  define NCBILOG_UINT8_FORMAT_SPEC "I64"
00274 #elif defined(NCBI_OS_MSWIN)
00275    typedef          __int64   TNcbiLog_Int8;
00276    typedef unsigned __int64   TNcbiLog_UInt8;
00277 #  define NCBILOG_INT8_FORMAT_SPEC  "I64"
00278 #  define NCBILOG_UINT8_FORMAT_SPEC "I64u"
00279 #else
00280    typedef int64_t            TNcbiLog_Int8;
00281    typedef uint64_t           TNcbiLog_UInt8;
00282 #  define NCBILOG_INT8_FORMAT_SPEC  PRIi64
00283 #  define NCBILOG_UINT8_FORMAT_SPEC PRIu64
00284 #endif
00285 
00286 
00287 /** Process, thread and counter types
00288  */
00289 typedef TNcbiLog_UInt8 TNcbiLog_PID;
00290 typedef TNcbiLog_UInt8 TNcbiLog_TID;
00291 typedef TNcbiLog_UInt8 TNcbiLog_Counter;
00292 
00293 
00294 /** Declaration for thread-specific context
00295  */
00296 struct SContext_tag;
00297 typedef struct SContext_tag* TNcbiLog_Context;
00298 
00299 
00300 
00301 /******************************************************************************
00302  *  Logging setup functions
00303  */
00304 
00305 /** Initializing NcbiLog API.
00306  *  This function should be called before any other API's function.
00307  *  Only first call of NcbiLog_Init() have effect. All subsequent calls
00308  *  will be ignored. Preferable, in MT applications it should be called
00309  *  before creating any child thread uses logging.
00310  *
00311  *  @param appname
00312  *    Set the application name shown in logs and used for logfile names.
00313  *    By default the name is unknown. The application name can be set only
00314  *    once at API initialization (using NcbiLog_Init() call).
00315  *    This name could include path and extension, only base name will be
00316  *    used to show in logs. Also, any spaces contained in the base file 
00317  *    name will be URL-encoded.
00318  *    Also, the application name can be hard-coded on the compilation step,
00319  *    using "-D NCBI_C_LOG_APPNAME=appname" in the compiler's command line
00320  *    for this API. Hard-coded name have a priority over the passed parameter.
00321  *  @param mt_lock
00322  *    User defined MT lock. It is necessary to use NcbiLog API in
00323  *    multi-threaded applications.
00324  *  @param own_mt_lock
00325  *    MT lock ownership flag. If eNcbiLog_MT_TakeOwnership is passed,
00326  *    then the MT lock handler will be destroyed in NcbiLog_Destroy().
00327  *  @note
00328  *    It is recommended to call NcbiLog_InitST() instead of NcbiLog_Init[MT]()
00329  *    if you don't use logging simultaneously from some threads.
00330  *  @sa
00331  *    NcbiLog_InitMT, NcbiLog_InitST, NcbiLog_Destroy, NcbiLog_MTLock_Create, 
00332  *    NcbiLog_Context_Create
00333  *  @note
00334  *    Sometimes, simplified logging initialization can be used. For details
00335  *    please see NcbiLog_Context_Create() description and comments at 
00336  *    the beginning of this file.
00337  */
00338 extern void NcbiLog_Init(const char*               appname, 
00339                          TNcbiLog_MTLock           mt_lock, 
00340                          ENcbiLog_MTLock_Ownership mt_lock_ownership);
00341 
00342 
00343 /** Version of NcbiLog_Init with default MT lock implementation.
00344  *  This function should be called before any other API's function.
00345  *  Preferable, in MT applications it should be called before
00346  *  creating any child thread uses logging.
00347  *
00348  *  @sa NcbiLog_Init, NcbiLog_InitST
00349  */
00350 extern void NcbiLog_InitMT(const char* appname);
00351 
00352 
00353 /** Version of NcbiLog_Init to use in single-threaded applications.
00354  *  This function should be called before any other API's function.
00355  *
00356  *  @note
00357  *    You can call NcbiLog_InitST() instead of NcbiLog_Init[MT]()
00358  *    in MT applications also if you don't use logging from some
00359  *    threads simultaneously. This will turn off API's MT-safety.
00360  *  @sa NcbiLog_Init, NcbiLog_InitMT
00361  */
00362 extern void NcbiLog_InitST(const char* appname);
00363 
00364 
00365 /** Version of NcbiLog_Init to use with NcbiLog_Context_* functions only.
00366  *  This function should be called before any other API's function.
00367  *  Only first call of NcbiLog_InitForAttachedContext() have effect.
00368  *  All subsequent calls will be ignored. You can skip it if you don't 
00369  *  wish to set up an application name for logging, all initialization
00370  *  will be done in background.
00371  *
00372  *  @note
00373  *    Default MT locking implementation will be used, you cannot use
00374  *    your own locking using with this type on initialization.
00375  *  @note
00376  *    For details please see NcbiLog_Context_Create() description
00377  *    and comments at the beginning of this file.
00378  *  @param appname
00379  *    Set the application name shown in logs and used for logfile names.
00380  *    By default the name is unknown. The application name can be set only
00381  *    once at API initialization.
00382  *    This name could include path and extension, only base name will be
00383  *    used to show in logs. Also, any spaces contained in the base file 
00384  *    name will be URL-encoded.
00385  *    Also, the application name can be hard-coded on the compilation step,
00386  *    using "-D NCBI_C_LOG_APPNAME=appname" in the compiler's command line
00387  *    for this API. Hard-coded name have a priority over passed parameter.
00388  *  @sa 
00389  *    NcbiLog_Init, NcbiLog_InitForAttachedContextST, NcbiLog_Context_Create
00390  */
00391 extern void NcbiLog_InitForAttachedContext(const char* appname);
00392 
00393 
00394 /** Version of NcbiLog_InitForAttachedContext() intended to use 
00395   * in single-threaded applications. Use it if you use API from single thread
00396   * only, it can be a little bit faster than NcbiLog_InitForAttachedContext()
00397   * because don't use MT-safety.
00398   *
00399   * @sa 
00400   *   NcbiLog_InitForAttachedContext, NcbiLog_Init, NcbiLog_InitST,
00401   *   NcbiLog_Context_Create
00402   */
00403 extern void NcbiLog_InitForAttachedContextST(const char* appname);
00404 
00405 
00406 /** Destroy NcbiLog API.
00407  *  This function should be called last. After it any other API's calls
00408  *  will be ignored. For MT applications see also NcbiLog_Destroy_Thread().
00409  *
00410  *  @sa
00411  *    NcbiLog_Init, NcbiLog_InitForAttachedContext
00412  */
00413 extern void NcbiLog_Destroy(void);
00414 
00415 
00416 /** Destroy thread-specific NcbiLog API information.
00417  *  Each thread should call this function before termination, and
00418  *  before NcbiLog_Destroy() call.
00419  *  Calling any other API function in the current thread except
00420  *  NcbiLog_Destroy() is prohibited and can lead to application crash.
00421  *
00422  *  @note 
00423  *    Not necessary to call this function in single-threaded
00424  *    applications if NcbiLog_InitST() was used.
00425  *  @sa
00426  *    NcbiLog_Init, NcbiLog_InitST, NcbiLog_Destroy
00427  */
00428 extern void NcbiLog_Destroy_Thread(void);
00429 
00430 
00431 /** Set up diagnostics destination.
00432  *
00433  *  @param ds
00434  *    An enum value to specify an application's diagnostics destination.
00435  *  @return
00436  *    The diagnostic destination that was really set.
00437  *    It is not always possible to set up an destination for logging messages
00438  *    that specified in parameters and fallback can be used.
00439  *    See ENcbiLog_Destination description for details.
00440  * @note
00441  *    By default, if SetDestination() is not called or set to eNcbiLog_Default,
00442  *    and environment variable $NCBI_CONFIG__LOG__FILE is defined and not empty,
00443  *    its value will be used as base name for logfiles.
00444  *    It can have special value "-" to redirect all output to STDERR.
00445  *  @sa
00446  *    ENcbiLog_Destination, NcbiLog_Init
00447  */
00448 extern ENcbiLog_Destination NcbiLog_SetDestination(ENcbiLog_Destination ds);
00449 
00450 
00451 /** Set process ID (PID).
00452  *
00453  *  @note
00454  *    This method does not affect GUID value if called after starting logging.
00455  */
00456 extern void NcbiLog_SetProcessId(TNcbiLog_PID pid);
00457 
00458 
00459 /** Set thread ID (TID).
00460  *
00461  *  @note
00462  *    This method does not affect GUID value if called after starting logging.
00463  */
00464 extern void NcbiLog_SetThreadId (TNcbiLog_TID tid);
00465 
00466 
00467 /** Set current request ID (RID). 
00468  *  Calling this method before NcbiLog_AppRun() is not allowed.
00469  * 
00470  *  @note
00471  *    NcbiLog_SetRequestId() does not affect already started requests.
00472  *    Only newly started request will have new ID.
00473  *  @note
00474  *    NcbiLog_ReqStart() automaticaly increases request number. 
00475  *    So, next request will start with (rid + 1).
00476  *  @sa
00477  *    NcbiLog_GetRequestId, NcbiLog_ReqStart
00478  */
00479 extern void NcbiLog_SetRequestId(TNcbiLog_Counter rid);
00480 
00481 
00482 /** Get current request ID (RID).
00483  * 
00484  *  @sa
00485  *    NcbiLog_SetRequestId, NcbiLog_ReqStart
00486  */
00487 extern TNcbiLog_Counter NcbiLog_GetRequestId(void);
00488 
00489 
00490 /** Set the posting date and time.
00491  *  By default, system-provided time is used.
00492  *  It can speed up a logging if date/time is already known before calling any
00493  *  post function. It also can be used to alter the time of the posting.
00494  *  @param timer
00495  *    GMT date and time at which the message was posted (see time()).
00496  *    This time value will be converted to local date/time automatically.
00497  *    The current date/time will be used if this parameter is zero.
00498  *  @param nanoseconds
00499  *    Nanosecond part of the time.
00500  *  @attention
00501  *    The set value will be used for all subsequent postings!
00502  *    To start using system time again, call NcbiLog_SetTime(0,0).
00503  */
00504 extern void NcbiLog_SetTime(time_t timer, unsigned long nanoseconds);
00505 
00506 
00507 /** Set the host name.
00508  *  By default, this value is taken from the system.
00509  *
00510  *  @param host
00511  *    New host name.
00512  *    It will be set to 'UNK_HOST' if parameter is NULL or empty string.
00513  *  @note
00514  *    This method does not affect GUID value if called after starting logging.
00515  */
00516 extern void NcbiLog_SetHost(const char* host);
00517 
00518 
00519 /** Set client for the whole application.
00520  *  This setting is effective in between requests, and for the requests for
00521  *  which the client was not explicitly set (by calling NcbiLog_SetClient()).
00522  *  
00523  *  By default, this value is taken from the environment variables.
00524  *  If that is not populated, it is set to 'UNK_CLIENT'.
00525  *
00526  *  @param client
00527  *    New client name (IP address).
00528  *    It will be set to 'UNK_CLIENT' if parameter is NULL or empty string.
00529  *  @sa
00530  *    NcbiLog_SetClient
00531  */
00532 extern void NcbiLog_AppSetClient(const char* client);
00533 
00534 
00535 /** Set client for the request.
00536  *
00537  *  This setting is effective for a single request:
00538  *   - either for the current request -- if the call is made between
00539  *     NcbiLog_ReqStart() and NcbiLog_ReqStop();
00540  *   - or for the very next request -- if the call is made between
00541  *     NcbiLog_ReqStop() and NcbiLog_ReqStart().
00542  *  
00543  *  If the client is not explicitly set for a request, this value is taken
00544  *  from the environment variables. If that is not populated, then 
00545  *  the application wide value (see NcbiLog_AppSetClient()) will be used
00546  *  for the request.
00547  *
00548  *  @attention
00549  *    NcbiLog_ReqStop() resets the client back to the application-wide value!
00550  *  @param client
00551  *    New client name (IP address).
00552  *    It will be set to 'UNK_CLIENT' if parameter is NULL or empty string.
00553  *  @sa
00554  *    NcbiLog_AppSetClient, NcbiLog_ReqStart, NcbiLog_ReqStop
00555  */
00556 extern void NcbiLog_SetClient(const char* client);
00557 
00558 
00559 /** Set session ID (SID) for the whole application.
00560  *
00561  *  This setting is effective in between requests, and for the requests for
00562  *  which the client was not explicitly set (by calling either
00563  *  NcbiLog_SetSession() or NcbiLog_NewSession()).
00564  *
00565  *  By default, SID is taken from the HTTP_NCBI_SID environment variable;
00566  *  if that is not set, then -- from NCBI_LOG_SESSION_ID environment variable;
00567  *  if that is not set, then -- SID is set to 'UNK_SESSION'.
00568  *
00569  *  @param session
00570  *    New session ID. (It will be URL-encoded.)
00571  *    It will be set to 'UNK_SESSION' if the parameter is NULL or empty string.
00572  *  @sa
00573  *    NcbiLog_AppNewSession, NcbiLog_SetSession, NcbiLog_NewSession
00574  */
00575 extern void NcbiLog_AppSetSession(const char* session);
00576 
00577 
00578 /** Auto-generate and then set brand-new application-wide session ID (SID).
00579  *
00580  *  @sa NcbiLog_AppSetSession
00581  */
00582 extern void NcbiLog_AppNewSession(void);
00583 
00584 
00585 /** Set session ID (SID) for the request.
00586  *
00587  *  This setting is effective for a single request:
00588  *   - either for the current request -- if the call is made between
00589  *     NcbiLog_ReqStart() and NcbiLog_ReqStop();
00590  *   - or for the very next request -- if the call is made between
00591  *     NcbiLog_ReqStop() and NcbiLog_ReqStart().
00592  *
00593  *  If SID is not explicitly set for a request, then the application-
00594  *  wide value (per NcbiLog_AppSetSession() or
00595  *  NcbiLog_AppNewSession()) will be used for the request.
00596  *
00597  *  @attention
00598  *    NcbiLog_ReqStop() resets the SID back to the application-wide value!
00599  *  @param session
00600  *    New session ID. (It will be URL-encoded.)
00601  *    It will be set to 'UNK_SESSION' if the parameter is NULL or empty string.
00602  *  @sa
00603  *    NcbiLog_AppSetSession, NcbiLog_AppNewSession,
00604  *    NcbiLog_ReqStart, NcbiLog_ReqStop
00605  */
00606 extern void NcbiLog_SetSession(const char* session);
00607 
00608 
00609 /** Auto-generate and then set brand-new session ID (SID) for the request.
00610  *
00611  *  @sa NcbiLog_SetSession
00612  */
00613 extern void NcbiLog_NewSession(void);
00614 
00615 
00616 /** Set hit ID (HID, a.k.a. PHID) for the whole application.
00617  *
00618  *  This setting is effective in between requests, and for the requests
00619  *  for which the client was not explicitly set (by calling either
00620  *  NcbiLog_SetHitID() or NcbiLog_NewHitID()).
00621  *
00622  *  By default, (P)HID is taken from the HTTP_NCBI_PHID environment variable;
00623  *  if that is not set, then -- from NCBI_LOG_HIT_ID environment variable;
00624  *  if that is not set, then -- it is set to an empty string.
00625  *
00626  *  @attention
00627  *    If hit ID has been logged for application, the call will be ignored.
00628  *    See NcbiLog_GetNextSubHitID().
00629  *  @param hit_id
00630  *    New (P)HID. (It will be URL-encoded.)
00631  *    (P)HID will be unset if the parameter is NULL or point to empty string,
00632  *    and PHID has not logged yet.
00633  *  @sa
00634  *    NcbiLog_AppNewHitID, NcbiLog_SetHitID, NcbiLog_NewHitID,
00635  *    NcbiLog_GetNextSubHitID
00636  */
00637 extern void NcbiLog_AppSetHitID(const char* hit_id);
00638 
00639 
00640 /** Auto-generate and then set brand-new application-wide hit ID
00641  *  (HID, a.k.a. PHID).
00642  *
00643  *  @attention
00644  *    It calls by default on NcbiLog_AppStart() if no user defined PHID
00645  *    or environment variables are available. So usually you don't need
00646  *    to call it manually. PHID can be redefined with NcbiLog_AppSetHitID()
00647  *    at any time if not logged yet.
00648  *  @attention
00649  *    If hit ID has been already logged for application, the call
00650  *    will be ignored. See NcbiLog_GetNextSubHitID().
00651  *  @sa 
00652  *    NcbiLog_AppSetHitID, NcbiLog_GetNextSubHitID
00653  */
00654 extern void NcbiLog_AppNewHitID(void);
00655 
00656 
00657 /** Set hit ID (HID, a.k.a. PHID) for the request.
00658  *
00659  *  This setting is effective for a single request:
00660  *   - either for the current request -- if the call is made between
00661  *     NcbiLog_ReqStart() and NcbiLog_ReqStop();
00662  *   - or for the very next request -- if the call is made between
00663  *     NcbiLog_ReqStop() and NcbiLog_ReqStart().
00664  *
00665  *  If (P)HID is not explicitly set for a request, then the application-
00666  *  wide value (per NcbiLog_AppSetHitID() or
00667  *  NcbiLog_AppNewHitID()) will be used for the request.
00668  *
00669  *  @attention
00670  *    NcbiLog_ReqStop() resets the (P)HID back to the application-wide value!
00671  *  @attention
00672  *    If hit ID has been already logged for the current request, the call
00673  *    will be ignored. See NcbiLog_GetNextSubHitID().
00674  *  @param hit_id
00675  *    New (P)HID. (It will be URL-encoded.)
00676  *    (P)HID will be unset if the parameter is NULL or point to empty string,
00677  *    and PHID has not logged yet.
00678  *  @sa
00679  *    NcbiLog_AppSetHitID, NcbiLog_AppNewHitID,
00680  *    NcbiLog_ReqStart, NcbiLog_ReqStop, NcbiLog_GetNextSubHitID
00681  */
00682 extern void NcbiLog_SetHitID(const char* hit_id);
00683 
00684 
00685 /** Auto-generate and then set brand-new hit ID (HID, a.k.a. PHID)
00686  *  for the request.
00687  *
00688  *  @attention
00689  *    If hit ID has been already logged for the current request, the call
00690  *    will be ignored. See NcbiLog_GetNextSubHitID().
00691  *  @sa
00692  *    NcbiLog_SetHitID, NcbiLog_GetNextSubHitID
00693  */
00694 extern void NcbiLog_NewHitID(void);
00695 
00696 
00697 /** Generate a sub-hit ID based on the currently effective
00698  *  (whether it's request-specific or application-wide) hit ID.
00699  *
00700  *  This function automatically log current app/request hit ID if not logged yet.
00701  *  This is a single method that do logging such information.
00702  *
00703  *  @return
00704  *    Generated sub-hit ID.
00705  *    If hit id is not set, return NULL.
00706  *  @attention
00707  *    The caller is responsible for freeing the returned sub-hit ID string!
00708  *    Use free() or NcbiLog_FreeMemory().
00709  *  @sa
00710   *   NcbiLog_AppSetHitID, NcbiLog_SetHitID, NcbiLog_FreeMemory
00711  */
00712 extern char* NcbiLog_GetNextSubHitID(void);
00713 
00714 
00715 /** Free memory allocated inside the C logging API.
00716  *
00717  * Can be useful when using from JAVA/Python wrappers, that cannot deallocate
00718  * memory directly.
00719  *
00720  *  @param ptr
00721  *    Pointer to allocated memory.
00722  *  @sa
00723   *   NcbiLog_GetNextSubHitID
00724  */
00725 extern void NcbiLog_FreeMemory(void* ptr);
00726 
00727 
00728 /** Set new posting severity threshold.
00729  *  All messages with severity lower than specified will be ignored.
00730  *
00731  *  @return
00732  *    The severity threshold that was in effect before this call.
00733  */
00734 extern ENcbiLog_Severity NcbiLog_SetPostLevel(ENcbiLog_Severity sev);
00735 
00736 
00737 
00738 /******************************************************************************
00739  *  NcbiLog context functions.
00740  *  NOTE:  see comments at the beginning of this file.
00741  */
00742 
00743 /** Create new thread-specific logging context object.
00744  *  These context-specific methods to create, attach, detach and
00745  *  destroy thread-specific logging context objects allow to separate
00746  *  context from the API, store it somewhere else and use when necessary,
00747  *  even from different threads. Because the API initialization
00748  *  can be done in background, it is impossible to pass application name
00749  *  used in each logging message, so it will be "UNKNOWN" by default.
00750  *  But, you can call NcbiLog_Init() or NcbiLog_InitForAttachedContext(),
00751  *  or one of its variants. Or, you can hard-code application name on the
00752  *  compilation step, using "-D NCBI_C_LOG_APPNAME=appname" in the compiler's
00753  *  command line for this API.
00754  *
00755  *  @note
00756  *    You should call this method first, before using any other API methods.
00757  *  @note
00758  *    Created context have a thread id of the thread that created it.
00759  *    Thread id can be changed if necessary using NcbiLog_SetThreadId()
00760  *    after attaching context to the API.
00761  *  @note
00762  *    Default MT locking implementation will be used in MT configurations,
00763  *    you cannot use your own MT-handler with this type on initialization.
00764  *  @note
00765  *    Also, please read NcbiLog_Init() and comments at the beginning of this file.
00766  *  @return
00767  *    Handle to newly created context object or NULL on error.
00768  *  @sa
00769  *    NcbiLog_Context_Attach, NcbiLog_Context_Detach, NcbiLog_Context_Destroy,
00770  *    NcbiLog_ForAttachedContext
00771  */
00772 extern TNcbiLog_Context NcbiLog_Context_Create(void);
00773 
00774 
00775 /** Attach logging context object to the C Logging API.
00776  *
00777  *  @note
00778  *    You should call this method before logging or using any other
00779  *    methods that change context information. All API methods work
00780  *    with attached context only, otherwise you can get unexpected results.
00781  *  @param ctx
00782  *    A handle previously obtained from NcbiLog_Context_Create().
00783  *  @return
00784  *    Non-zero value if the requested operation was successful.
00785  *    Also, return zero value if some other context is already attached.
00786  *  @sa
00787  *    NcbiLog_Context_Create, NcbiLog_Context_Attach, NcbiLog_Context_Destroy
00788  */
00789 extern int /*bool*/ NcbiLog_Context_Attach(TNcbiLog_Context ctx);
00790 
00791 
00792 /** Detach logging context object from the C Logging API.
00793  *
00794  *  @note
00795  *    The C Logging API cannot be used without any context attached.
00796  *  @return
00797  *    Non-zero value if the requested operation was successful.
00798  *  @sa
00799  *    NcbiLog_Context_Create, NcbiLog_Context_Attach, NcbiLog_Context_Destroy
00800  */
00801 extern void NcbiLog_Context_Detach(void);
00802 
00803 
00804 /** Destroy context structure.
00805  *
00806  *  @note
00807  *    NcbiLog_Context_Detach() should be called before context destroying.
00808  *  @param ctx
00809  *    A handle previously obtained from NcbiLog_Context_Create().
00810  *  @sa
00811  *    NcbiLog_Context_Create, NcbiLog_Context_Attach, NcbiLog_Context_Detach
00812  */
00813 extern void NcbiLog_Context_Destroy(TNcbiLog_Context ctx);
00814 
00815 
00816 
00817 /******************************************************************************
00818  *  NcbiLog posting functions
00819  */
00820 
00821 /** Should be called as soon as possible during application initialization.
00822  *  Writes the 'start' line to the <appname>.log, including the command line.
00823  *  Calling this function early ensures that the start time of the application
00824  *  is recorded; that data is later used by NcbiLog_AppStop() to calculate 
00825  *  the application runtime duration. If not called explicitly,
00826  *  NcbiLog_AppStart() is called by most other functions (but application
00827  *  arguments will not be logged in this case).
00828  *
00829  *  @param argc
00830  *    The count of arguments that follow in argv (from main()).
00831  *  @param argv
00832  *    An array of null-terminated strings representing command-line
00833  *    arguments of the program (from main()).
00834  *  @sa
00835  *    NcbiLog_AppRun, NcbiLog_AppStop
00836  */
00837 extern void NcbiLog_AppStart(const char* argv[]);
00838 
00839 
00840 /** Should be called after the application is initialized and before its
00841  *  main part.Just changes the application state shown in the log to 'A'.
00842  *  It does not cause any information to be logged.
00843  *
00844  *  @sa NcbiLog_AppStart, NcbiLog_AppStop
00845  */
00846 extern void NcbiLog_AppRun(void);
00847 
00848 
00849 /** Should be called immediately prior to the application exit. 
00850  *  Logs the 'stop' line to the <appname>.log files.
00851  *  Calculates the application runtime duration based on a start time
00852  *  recorded when the application starts up.
00853  *
00854  *  @sa NcbiLog_AppStart, NcbiLog_AppStopSignal
00855  */
00856 extern void NcbiLog_AppStop(int exit_status);
00857 
00858 
00859 /** The same as NcbiLog_AppStop(), except it also accepts a signal number,
00860  *  if application exited due to a signal.
00861  *
00862  *  @sa NcbiLog_AppStart, NcbiLog_AppStop
00863  */
00864 extern void NcbiLog_AppStopSignal(int exit_status, int exit_signal);
00865 
00866 
00867 /** Should be called once application startup is complete, before any
00868  *  request processing code is run. Writes the 'request-start' line to the
00869  *  <appname>.log file.
00870  *  Sets or resets the start time of the current request; that data is later
00871  *  used by NcbiLog_ReqStop() to calculate the request runtime duration. 
00872  *  Can optionally be passed a pointer to NULL-terminated array with
00873  *  parameters, as key/value pairs; that data will be logged.
00874  *  This method also resets the client and session information. If the user
00875  *  has provided alternate info, it may be overridden as a side-effect of
00876  *  calling this method. Automatically increase request id number.
00877  *
00878  *  @sa NcbiLog_SetRequestId, NcbiLog_ReqStop
00879  */
00880 extern void NcbiLog_ReqStart(const SNcbiLog_Param* params);
00881 
00882 
00883 /** Should be called once request processing initialization is complete.
00884  *  It does not cause any information to be logged. Just changes
00885  *  the application state shown in the log to 'R'. 
00886  *
00887  *  @sa NcbiLog_ReqStart, NcbiLog_ReqStop
00888  */
00889 extern void NcbiLog_ReqRun(void);
00890 
00891 
00892 /** Should be called once request processing is complete. Writes the
00893  * 'request-stop' line to the <appname>.log file. 
00894  *  Calculates request runtime duration based on a start time recorded
00895  *  when NcbiLog_ReqStart() is called.
00896  *  Session and client information is reset to UNK_SESSION and UNK_CLIENT.
00897  *
00898  *  @sa NcbiLog_ReqStart
00899  */
00900 extern void NcbiLog_ReqStop(int status, size_t bytes_rd, size_t bytes_wr);
00901 
00902 
00903 /** Can be called at any time. Writes the 'extra' line to the <appname>.log
00904  *  file. Can take a pointer to NULL-terminated array with parameters,
00905  *  as key/value pairs; that data will be logged. Appropriate for logging
00906  *  thing such as HTTP referrer information and cookie values. Should NOT
00907  *  be used for executing tracing or logging of debugging info -- see 
00908  *  the NcbiLog_Trace function for those purposes.
00909  */
00910 extern void NcbiLog_Extra(const SNcbiLog_Param* params);
00911 
00912 
00913 /** Can be called at any time. Writes the 'perf' line to the <appname>.log
00914  *  file. Used to log a performance information. Takes status code of some
00915  *  operation, its execution time and a pointer to NULL-terminated array with
00916  *  parameters, as key/value pairs.
00917  */
00918 extern void NcbiLog_Perf(int status, double timespan,
00919                          const SNcbiLog_Param* params);
00920 
00921 
00922 /** Writes a message to the <appname>.trace file at level 'TRACE'.
00923  *  Note that the default log level is INFO, meaning that unless the log
00924  *  level is explicitly set lower, messages logged via TRACE will not be
00925  *  seen or recorded.
00926  */
00927 extern void NcbiLog_Trace(const char* msg);
00928 
00929 
00930 /** Writes a message to the <appname>.trace file at level 'INFO'.
00931  *  Note that the default log level is INFO, meaning that these messages
00932  *  will be stored to disk or sent to stderr/stdout.
00933  */
00934 extern void NcbiLog_Info(const char* msg);
00935 
00936 
00937 /** Writes a message to the <appname>.err log at level 'WARNING'.
00938  */
00939 extern void NcbiLog_Warning(const char* msg);
00940 
00941 
00942 /** Writes a message to the <appname>.err log at level 'ERROR'.
00943  */
00944 extern void NcbiLog_Error(const char* msg);
00945 
00946 
00947 /** Writes a message to the <appname>.err log at level 'CRITICAL'.
00948  */
00949 extern void NcbiLog_Critical(const char* msg);
00950 
00951 
00952 /** Writes a message to the <appname>.err log at level 'FATAL' and then
00953  *  terminate the application.
00954  */
00955 extern void NcbiLog_Fatal(const char* msg);
00956 
00957 
00958 /* extern void NcbiLog_PostEx(ENcbiLog_Severity severity, const char* msg, const SNcbiLog_PostCtx* ctx); */
00959 
00960 #ifdef __cplusplus
00961 }  /* extern "C" */
00962 #endif
00963 
00964 
00965 /* @} */
00966 
00967 #endif /* NCBI_C_LOG__H */
Modified on Fri Sep 19 19:28:37 2014 by modify_doxy.py rev. 426318