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

Go to the SVN repository for this file.

1 #ifndef CONNECT___NCBI_CORE__H
2 #define CONNECT___NCBI_CORE__H
3 
4 /* $Id: ncbi_core.h 101608 2024-01-11 16:56:03Z lavr $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Author: Denis Vakatov
30  *
31  * File Description:
32  * @file ncbi_core.h
33  * Types and code shared by all "ncbi_*.[ch]" modules.
34  *
35  * I/O status and direction:
36  * enum: EIO_ReadMethod
37  * enum: EIO_WriteMethod
38  * enum: EIO_Event
39  * enum: EIO_Status, verbal: IO_StatusStr()
40  *
41  * Critical section (basic multi-thread synchronization):
42  * handle: MT_LOCK
43  * enum: EMT_Lock
44  * callbacks: (*FMT_LOCK_Handler)(), (*FMT_LOCK_Cleanup)()
45  * methods: MT_LOCK_Create(), MT_LOCK_AddRef(), MT_LOCK_Delete(),
46  * MT_LOCK_Do()
47  *
48  * Tracing and logging:
49  * handle: LOG
50  * enum: ELOG_Level, verbal: LOG_LevelStr()
51  * flags: TLOG_FormatFlags, ELOG_FormatFlags
52  * callbacks: (*FLOG_Handler)(), (*FLOG_Cleanup)()
53  * methods: LOG_Create(), LOG_Reset(), LOG_AddRef(), LOG_Delete(),
54  * LOG_Write(), LOG_WriteInternal()
55  *
56  * Registry:
57  * handle: REG
58  * enum: EREG_Storage
59  * callbacks: (*FREG_Get)(), (*FREG_Set)(), (*FREG_Cleanup)()
60  * methods: REG_Create(), REG_Reset(), REG_AddRef(), REG_Delete(),
61  * REG_Get(), REG_Set()
62  *
63  */
64 
65 #include <connect/ncbi_types.h>
66 
67 
68 /** @addtogroup UtilityFunc
69  *
70  * @{
71  */
72 
73 
74 #ifdef __cplusplus
75 extern "C" {
76 #endif
77 
78 
79 /******************************************************************************
80  * I/O
81  */
82 
83 
84 /** I/O read method.
85  * @sa
86  * EIO_WriteMethod
87  */
88 typedef enum {
89  eIO_ReadPeek, /**< do eIO_ReadPlain but leave data in input queue */
90  eIO_ReadPlain, /**< read readily available data only, wait if none */
91  eIO_ReadPersist /**< read exactly as much as requested, w/waits */
93 
94 
95 /** I/O write method.
96  * @sa
97  * EIO_ReadMethod
98  */
99 typedef enum {
100  eIO_WriteNone, /**< invalid reserved opcode, not for use! */
101  eIO_WritePlain, /**< write as much as possible, report back how much */
102  eIO_WritePersist, /**< write exactly as much as specified, w/waits */
103  eIO_WriteOutOfBand /**< write out-of-band chunk of urgent data (if supp)*/
105 
106 
107 /** I/O event (or direction).
108  * @note
109  * Internally, these constants are used as bit-values, and therefore must not
110  * be changed in this header. On the other hand, user code should not rely
111  * on the values of these constants, either.
112  * @warning
113  * Careful with an unfortunate naming similarity of eIO_Close from this enum
114  * and EIO_Status::eIO_Closed -- do not mix the two!
115  * @sa
116  * SOCK_Wait, SOCK_Poll, CONN_Wait, SOCK_SetTimeout, CONN_SetTimeout
117  */
118 typedef enum {
119  eIO_Open = 0, /**< also serves as no-event indicator in SOCK_Poll */
120  eIO_Read = 1, /**< read */
121  eIO_Write = 2, /**< write */
122  eIO_ReadWrite = 3, /**< eIO_Read | eIO_Write (also, eCONN_OnFlush) */
123  eIO_Close = 4 /**< also serves as an error indicator in SOCK_Poll */
125 
126 
127 /** I/O status.
128  * @warning
129  * Careful with an unfortunate naming similarity of eIO_Closed from this enum
130  * and EIO_Event::eIO_Close -- do not mix the two!
131  */
132 typedef enum {
133  eIO_Success = 0, /**< everything is fine, no error occurred */
134  eIO_Timeout, /**< timeout expired before any I/O succeeded */
135  eIO_Reserved, /**< reserved status code -- DO NOT USE! */
136  eIO_Interrupt, /**< signal arrival prevented any I/O to succeed */
137  eIO_InvalidArg, /**< bad argument / parameter value(s) supplied */
138  eIO_NotSupported, /**< operation is not supported or is not available */
139  eIO_Unknown, /**< unknown I/O error (likely fatal but can retry) */
140  eIO_Closed /**< connection is / has been closed, EOF condition */
141 #define EIO_N_STATUS 8
142 } EIO_Status;
143 
144 
145 /** Get the text form of an enum status value.
146  * @param status
147  * An enum value to get the text form for
148  * @return
149  * Verbal description of the I/O status
150  * @warning
151  * Returns NULL on out-of-bound values
152  * @note
153  * Reserved status code(s) returned as an empty string ("")
154  * @sa
155  * EIO_Status
156  */
157 extern NCBI_XCONNECT_EXPORT const char* IO_StatusStr(EIO_Status status);
158 
159 
160 
161 /******************************************************************************
162  * MT locking
163  */
164 
165 
166 /** Lock handle -- keeps all data needed for the locking and for the cleanup.
167  * @sa
168  * CORE_SetLOCK
169  */
170 struct MT_LOCK_tag;
171 typedef struct MT_LOCK_tag* MT_LOCK;
172 
173 
174 /** Set the lock/unlock callback function and its data for MT critical section.
175  * @note
176  * If the RW-lock functionality is not provided by the callback, then:
177  * eMT_LockRead <==> eMT_Lock
178  *
179  */
180 typedef enum {
181  eMT_Lock, /**< lock critical section */
182  eMT_LockRead, /**< lock critical section for reading */
183  eMT_Unlock, /**< unlock critical section */
184  eMT_TryLock, /**< try to lock, return immediately */
185  eMT_TryLockRead /**< try to lock for reading, return immediately */
187 
188 
189 /** MT locking callback (operates like a [recursive] mutex or RW-lock).
190  * @param data
191  * See "data" in MT_LOCK_Create()
192  * @param how
193  * As passed to MT_LOCK_Do()
194  * @return
195  * Non-zero value if the requested operation was successful.
196  * @note
197  * The "-1" value is reserved for unset handler; you also may want to return
198  * "-1" if your locking function does no locking, and you don't consider it as
199  * an error, but still want the caller to be aware of this "rightful
200  * non-doing" as opposed to the "rightful doing".
201  * @sa
202  * MT_LOCK_Create, MT_LOCK_Delete
203  */
204 typedef int/*bool*/ (*FMT_LOCK_Handler)
205 (void* data,
206  EMT_Lock how
207  );
208 
209 /** MT lock cleanup callback.
210  * @param data
211  * See "data" in MT_LOCK_Create()
212  * @sa
213  * MT_LOCK_Create, MT_LOCK_Delete
214  */
215 typedef void (*FMT_LOCK_Cleanup)
216 (void* data
217  );
218 
219 
220 /** Create a new MT lock (with an internal reference count set to 1).
221  * @param data
222  * Unspecified data to call "handler" and "cleanup" with
223  * @param handler
224  * Locking callback
225  * @param cleanup
226  * Cleanup callback
227  * @sa
228  * FMT_LOCK_Handler, FMT_LOCK_Cleanup, MT_LOCK_Delete
229  */
231 (void* data,
234  );
235 
236 
237 /** Increment internal reference count by 1, then return "lk".
238  * @param lk
239  * A handle previously obtained from MT_LOCK_Create
240  * @sa
241  * MT_LOCK_Create, MT_LOCK_Delete
242  */
244 
245 
246 /** Decrement internal reference count by 1, and if it reaches 0, then
247  * destroy the handle, call "lk->cleanup(lk->data)", and return NULL;
248  * otherwise (if the reference count is still > 0), return "lk".
249  * @param lk
250  * A handle previously obtained from MT_LOCK_Create
251  * @sa
252  * MT_LOCK_Create, FMT_LOCK_Cleanup
253  */
255 
256 
257 /** Call "lk->handler(lk->data, how)".
258  * @param lk
259  * A handle previously obtained from MT_LOCK_Create
260  * @param how
261  * Whether to lock (and how: read, write) or to unlock
262  * @return
263  * Value returned by the lock handler ("handler" in MT_LOCK_Create()).
264  * If the lock handler is not specified then always return "-1" (noop).
265  * @note
266  * Use MT_LOCK_Do() to avoid overhead!
267  * @sa
268  * MT_LOCK_Create, FMT_LOCK_Handler, EMT_Lock
269  */
270 #define MT_LOCK_Do(lk, how) ((lk) ? MT_LOCK_DoInternal((lk), (how)) : -1)
271 extern NCBI_XCONNECT_EXPORT int/*bool*/ MT_LOCK_DoInternal
272 (MT_LOCK lk,
273  EMT_Lock how
274  );
275 
276 
277 /******************************************************************************
278  * Error handling and logging
279  */
280 
281 
282 /** Log handle -- keeps all data needed for the logging and for the cleanup.
283  * @sa
284  * CORE_SetLOG
285  */
286 struct LOG_tag;
287 typedef struct LOG_tag* LOG;
288 
289 
290 /** Log severity level.
291  */
292 typedef enum {
295  eLOG_Info = eLOG_Note, /**< In C++ Toolkit "Info" is used, not "Note" */
299  eLOG_Fatal
301 
302 
303 /** Obtain verbal representation of an enum level value.
304  * @param level
305  * An enum value to get the text form for
306  * @return
307  * Verbal description of the log level
308  * @sa
309  * ELOG_Level
310  */
311 extern NCBI_XCONNECT_EXPORT const char* LOG_LevelStr(ELOG_Level level);
312 
313 
314 /** Message and miscellaneous data to pass to log post callback FLOG_Handler.
315  * @param dynamic
316  * if non-zero then LOG_WriteInternal() calls free(message) before returning
317  * @param message
318  * A message to post, can be NULL
319  * @param level
320  * A message level
321  * @param module
322  * A module string to post, can be NULL
323  * @param file
324  * A file name to post, can be NULL
325  * @param line
326  * A line number within the file (above) to post, can be 0
327  * @param raw_data
328  * Raw data to log (usually NULL)
329  * @param raw_size
330  * Size of the raw data (usually zero)
331  * @param err_code
332  * Error code of the message
333  * @param err_subcode
334  * Error subcode of the message
335  * @sa
336  * FLOG_Handler, LOG_Create, LOG_WriteInternal, LOG_Write
337  */
338 typedef struct {
339  int/*bool*/ dynamic;
340  const char* message;
342  const char* module;
343  const char* func;
344  const char* file;
345  int line;
346  const void* raw_data;
347  size_t raw_size;
348  int err_code;
350 } SLOG_Message;
351 
352 
353 /** Log post callback.
354  * @param data
355  * Unspeficied data as passed to LOG_Create() or LOG_Reset()
356  * @param mess
357  * Composed from arguments passed to LOG_WriteInternal()
358  * @sa
359  * SLOG_Message, LOG_Create, LOG_Reset, LOG_WriteInternal
360  */
361 typedef void (*FLOG_Handler)
362 (void* data,
363  const SLOG_Message* mess
364  );
365 
366 
367 /** Log cleanup callback.
368  * @param data
369  * Unspeficied data as passed to LOG_Create() or LOG_Reset()
370  * @sa
371  * LOG_Create, LOG_Reset
372  *
373  */
374 typedef void (*FLOG_Cleanup)
375 (void* data
376  );
377 
378 
379 /** Create a new LOG (with an internal reference count set to 1).
380  * @warning
381  * If non-NULL "lock" is specified then MT_LOCK_AddRef() is called on it here,
382  * and MT_LOCK_Delete() will be called on it when this LOG gets deleted.
383  * @param data
384  * Unspecified data to call "handler" and "cleanup" with
385  * @param handler
386  * Log post callback
387  * @param cleanup
388  * Cleanup callback
389  * @param lock
390  * Protective MT lock (may be NULL)
391  * @sa
392  * MT_LOCK, MT_LOCK_AddRef, FLOG_Handler, FLOG_Cleanup, LOG_Reset, LOG_Delete
393  */
395 (void* data,
398  MT_LOCK lock
399  );
400 
401 
402 /** Reset the "lg" to use the new "data", "handler" and "cleanup".
403  * @note
404  * It does not change the reference count of the log.
405  * @param lg
406  * A log handle previously obtained from LOG_Create
407  * @param data
408  * New user data
409  * @param handler
410  * New log post callback
411  * @param cleanup
412  * New cleanup callback
413  * @return
414  * lg (as passed in the first parameter)
415  * @sa
416  * LOG_Create
417  */
419 (LOG lg,
420  void* data,
423  );
424 
425 
426 /** Increment internal reference count by 1, then return "lg".
427  * @param lg
428  * A log handle previously obtained from LOG_Create
429  * @sa
430  * LOG_Create
431  */
433 
434 
435 /** Decrement internal reference count by 1, and if it reaches 0, then
436  * call "lg->cleanup(lg->data)", destroy the handle, and return NULL;
437  * otherwise (if reference count is still > 0), return "lg".
438  * @param lg
439  * A log handle previously obtained from LOG_Create
440  * @sa
441  * LOG_Create
442  */
444 
445 
446 /** Upon having filled SLOG_Message data from parameters, write a message
447  * (perhaps with raw data attached) to the log by calling LOG_WriteInternal().
448  * @note
449  * Do not call this function directly, if possible. Instead, use the
450  * LOG_WRITE() and LOG_DATA() macros from <connect/ncbi_util.h>!
451  * @param code
452  * Error code of the message
453  * @param subcode
454  * Error subcode of the message
455  * @param level
456  * The message severity
457  * @param module
458  * Module name (can be NULL)
459  * @param func
460  * Function name (can be NULL)
461  * @param file
462  * Source file name (can be NULL)
463  * @param line
464  * Source line within the file (can be 0 to omit the line number)
465  * @param message
466  * Message content
467  * @param raw_data
468  * Raw data to log (can be NULL)
469  * @param raw_size
470  * Size of the raw data (can be zero)
471  * @sa
472  * LOG_Create, ELOG_Level, LOG_WriteInternal, LOG_WRITE, LOG_DATA
473  */
475 (LOG lg,
476  int code,
477  int subcode,
478  ELOG_Level level,
479  const char* module,
480  const char* func,
481  const char* file,
482  int line,
483  const char* message,
484  const void* raw_data,
485  size_t raw_size
486 );
487 
488 
489 /** Write message (perhaps with raw data attached) to the log by calling
490  * "lg->handler(lg->data, mess)".
491  * @note
492  * Do not call this function directly, if possible. Instead, use the
493  * LOG_WRITE() and LOG_DATA() macros from <ncbi_util.h>!
494  * @warning
495  * This call free()s "mess->message" when "mess->dynamic" is set non-zero!
496  * @param lg
497  * A log handle previously obtained from LOG_Create
498  * @note
499  * In case of a fatal error (eLOG_Fatal found in mess->code), it calls abort()
500  * (in Debug builds) or _exit(-1) (in Release builds). Note that no exit
501  * handlers are run or any other normal process run-down procedure performed.
502  * @sa
503  * LOG_Create, ELOG_Level, FLOG_Handler, LOG_Write
504  */
506 (LOG lg,
507  const SLOG_Message* mess
508  );
509 
510 
511 /******************************************************************************
512  * Registry
513  */
514 
515 
516 /** Registry handle (keeps all data needed for the registry get/set/cleanup).
517  * @sa
518  * CORE_SetReg
519  */
520 struct REG_tag;
521 typedef struct REG_tag* REG;
522 
523 
524 /** Transient/Persistent storage.
525  * @sa
526  * REG_Get, REG_Set
527  */
528 typedef enum {
529  eREG_Transient = 0, /**< only in-memory storage while program runs */
530  eREG_Persistent /**< hard-copy storage across program runs */
532 
533 
534 /** Registry getter callback.
535  * Copy registry value stored in "section" under "name" to the "value" buffer.
536  * Look for a matching entry first in the transient storage, and then in the
537  * persistent storage.
538  * @note
539  * Do not modify "value" (leave it "as is", i.e. empty) if the requested entry
540  * was not found in the registry; then, return -1.
541  * @note
542  * Always terminate the "value" with '\0'.
543  * @note
544  * Do not put more than "value_size" bytes into "value" (incl. trailing '\0').
545  * @param data
546  * Unspecified data as passed to REG_Create or REG_Reset
547  * @param section
548  * Section name to search
549  * @param name
550  * Key name to search within the section
551  * @param value
552  * Empty value passed in, found (if any) value out
553  * @param value_size
554  * Size of "value" storage, must be greater than 0
555  * @return
556  * 1 if successfully found and stored; -1 if not found (the default is to be
557  * used); 0 if an error (including truncation) occurred
558  * @sa
559  * REG_Create, REG_Reset, REG_Get, FREG_Set
560  */
561 typedef int (*FREG_Get)
562 (void* data,
563  const char* section,
564  const char* name,
565  char* value,
566  size_t value_size
567  );
568 
569 
570 /** Registry setter callback.
571  * Store the "value" in the registry "section" under the "name" key, and
572  * according to "storage".
573  * @param data
574  * Unspecified data as passed to REG_Create or REG_Reset
575  * @param section
576  * Section name to add the key to
577  * @param name
578  * Key name to add to the section
579  * @param value
580  * Key value to associate with the key (NULL to deassociate, i.e. unset)
581  * @param storage
582  * How to store the new setting, temporarily or permanently
583  * @return
584  * Non-zero if successful (including replacing a value with itself)
585  * @sa
586  * REG_Create, REG_Reset, EREG_Storage, REG_Set, FREG_Get
587  */
588 typedef int/*bool*/ (*FREG_Set)
589 (void* data,
590  const char* section,
591  const char* name,
592  const char* value,
593  EREG_Storage storage
594  );
595 
596 
597 /** Registry cleanup callback.
598  * @param data
599  * Unspecified data as passed to REG_Create or REG_Reset
600  * @sa
601  * REG_Reset, REG_Delete
602  */
603 typedef void (*FREG_Cleanup)
604 (void* data
605  );
606 
607 
608 /** Create a new registry (with an internal reference count set to 1).
609  * @warning
610  * if non-NULL "lock" is specified then MT_LOCK_AddRef() is called on it here,
611  * and MT_LOCK_Delete() will be called on it when this REG gets destroyed.
612  * Passing NULL callbacks below causes limiting the functionality
613  * only to those operations that have the callbacks set for.
614  * @param data
615  * Unspecified data to call "set", "get" and "cleanup" with
616  * @param get
617  * Getter callback
618  * @param set
619  * Setter callback
620  * @param cleanup
621  * Cleanup callback
622  * @param lock
623  * Protective MT lock (may be NULL)
624  * @sa
625  * MT_LOCK, MT_LOCK_AddRef, REG_Get, REG_Set, REG_Reset, REG_Delete
626  */
628 (void* data,
629  FREG_Get get,
630  FREG_Set set,
632  MT_LOCK lock
633  );
634 
635 
636 /** Reset the registry handle to use the new "data", "set", "get",
637  * and "cleanup".
638  * @note
639  * No change to the internal reference count.
640  * @param rg
641  * Registry handle as previously obtained from REG_Create
642  * @param data
643  * New user data
644  * @param get
645  * New getter callback
646  * @param set
647  * New setter callback
648  * @param cleanup
649  * New cleanup callback
650  * @param do_cleanup
651  * Whether to call old cleanup (if any specified) for old data
652  * @sa
653  * REG_Create, REG_Delete
654  */
656 (REG rg,
657  void* data,
658  FREG_Get get,
659  FREG_Set set,
661  int/*bool*/ do_cleanup
662  );
663 
664 
665 /** Increment internal reference count by 1, then return "rg".
666  * @param rg
667  * Registry handle as previously obtained from REG_Create
668  * @sa
669  * REG_Create
670  */
672 
673 
674 /** Decrement internal reference count by 1, and if it reaches 0, then
675  * call "rg->cleanup(rg->data)", destroy the handle, and return NULL;
676  * otherwise (if the reference count is still > 0), return "rg".
677  * @param rg
678  * Registry handle as previously obtained from REG_Create
679  * @sa
680  * REG_Create
681  */
683 
684 
685 /** Copy the registry value stored in "section" under name "name" to buffer
686  * "value"; if the entry is found in both transient and persistent storages,
687  * then copy the one from the transient storage.
688  * If the specified entry is not found in the registry (or if there is no
689  * registry defined), and "def_value" is not NULL, then copy "def_value" to
690  * "value" (although, only up to "value_size" characters).
691  * @param rg
692  * Registry handle as previously obtained from REG_Create
693  * @param section
694  * Registry section name
695  * @param name
696  * Registry entry name
697  * @param value
698  * Buffer to receive the value of the requested entry, must be non-NULL
699  * @param value_size
700  * Maximal size of buffer "value", must be greater than 0
701  * @param def_value
702  * Default value (none if passed NULL or "")
703  * @return
704  * Return "value" if the found value, including the default, and with its '\0'
705  * terminator, fits entirely within "value_size"; return NULL if there was an
706  * error retrieving the value, or if it had to be truncated (but regardless,
707  * "value" must always be kept '\0'-terminated unless "value_size" was zero).
708  * @sa
709  * REG_Create, REG_Set
710  */
711 extern NCBI_XCONNECT_EXPORT const char* REG_Get
712 (REG rg,
713  const char* section,
714  const char* name,
715  char* value,
716  size_t value_size,
717  const char* def_value
718  );
719 
720 
721 /** Store the "value" into the registry section "section" under the key "name",
722  * and according to "storage".
723  * @param rg
724  * Registry handle as previously obtained from REG_Create
725  * @param section
726  * Section name to store the value into
727  * @param name
728  * Name to store the value under
729  * @param value
730  * The value to store (NULL to unset the parameter)
731  * @param storage
732  * Whether to store temporarily or permanently
733  * @return
734  * Non-zero if successful (including replacing a value with itself)
735  * @sa
736  * REG_Create, EREG_Storage, REG_Get
737  */
738 extern NCBI_XCONNECT_EXPORT int REG_Set
739 (REG rg,
740  const char* section,
741  const char* name,
742  const char* value,
743  EREG_Storage storage
744  );
745 
746 
747 #ifdef __cplusplus
748 } /* extern "C" */
749 #endif
750 
751 
752 /* @} */
753 
754 #endif /* CONNECT___NCBI_CORE__H */
Definition: set.hpp:45
void(*)(CSeq_entry_Handle seh, IWorkbench *wb, const CSerialObject &obj) handler
static void cleanup(void)
Definition: ct_dynamic.c:30
char data[12]
Definition: iconv.c:80
int(* FREG_Set)(void *data, const char *section, const char *name, const char *value, EREG_Storage storage)
Registry setter callback.
Definition: ncbi_core.h:589
ELOG_Level
Log severity level.
Definition: ncbi_core.h:292
int MT_LOCK_DoInternal(MT_LOCK lk, EMT_Lock how)
Definition: ncbi_core.c:260
ELOG_Level level
Definition: ncbi_core.h:341
MT_LOCK MT_LOCK_AddRef(MT_LOCK lk)
Increment internal reference count by 1, then return "lk".
Definition: ncbi_core.c:217
size_t raw_size
Definition: ncbi_core.h:347
EMT_Lock
Set the lock/unlock callback function and its data for MT critical section.
Definition: ncbi_core.h:180
const void * raw_data
Definition: ncbi_core.h:346
void(* FLOG_Handler)(void *data, const SLOG_Message *mess)
Log post callback.
Definition: ncbi_core.h:362
const char * file
Definition: ncbi_core.h:344
const char * REG_Get(REG rg, const char *section, const char *name, char *value, size_t value_size, const char *def_value)
Copy the registry value stored in "section" under name "name" to buffer "value"; if the entry is foun...
Definition: ncbi_core.c:567
REG REG_Delete(REG rg)
Decrement internal reference count by 1, and if it reaches 0, then call "rg->cleanup(rg->data)",...
Definition: ncbi_core.c:540
const char * module
Definition: ncbi_core.h:342
EREG_Storage
Transient/Persistent storage.
Definition: ncbi_core.h:528
REG REG_Create(void *data, FREG_Get get, FREG_Set set, FREG_Cleanup cleanup, MT_LOCK lock)
Create a new registry (with an internal reference count set to 1).
Definition: ncbi_core.c:484
int(* FMT_LOCK_Handler)(void *data, EMT_Lock how)
MT locking callback (operates like a [recursive] mutex or RW-lock).
Definition: ncbi_core.h:205
const char * func
Definition: ncbi_core.h:343
EIO_Status
I/O status.
Definition: ncbi_core.h:132
struct REG_tag * REG
Definition: ncbi_core.h:521
int err_subcode
Definition: ncbi_core.h:349
void REG_Reset(REG rg, void *data, FREG_Get get, FREG_Set set, FREG_Cleanup cleanup, int do_cleanup)
Reset the registry handle to use the new "data", "set", "get", and "cleanup".
Definition: ncbi_core.c:506
LOG LOG_AddRef(LOG lg)
Increment internal reference count by 1, then return "lg".
Definition: ncbi_core.c:353
void LOG_WriteInternal(LOG lg, const SLOG_Message *mess)
Write message (perhaps with raw data attached) to the log by calling "lg->handler(lg->data,...
Definition: ncbi_core.c:392
const char * IO_StatusStr(EIO_Status status)
Get the text form of an enum status value.
Definition: ncbi_core.c:56
LOG LOG_Create(void *data, FLOG_Handler handler, FLOG_Cleanup cleanup, MT_LOCK lock)
Create a new LOG (with an internal reference count set to 1).
Definition: ncbi_core.c:313
struct MT_LOCK_tag * MT_LOCK
Definition: ncbi_core.h:171
void LOG_Write(LOG lg, int code, int subcode, ELOG_Level level, const char *module, const char *func, const char *file, int line, const char *message, const void *raw_data, size_t raw_size)
Upon having filled SLOG_Message data from parameters, write a message (perhaps with raw data attached...
Definition: ncbi_core.c:424
EIO_ReadMethod
I/O read method.
Definition: ncbi_core.h:88
MT_LOCK MT_LOCK_Delete(MT_LOCK lk)
Decrement internal reference count by 1, and if it reaches 0, then destroy the handle,...
Definition: ncbi_core.c:234
struct LOG_tag * LOG
Definition: ncbi_core.h:287
int(* FREG_Get)(void *data, const char *section, const char *name, char *value, size_t value_size)
Registry getter callback.
Definition: ncbi_core.h:562
MT_LOCK MT_LOCK_Create(void *data, FMT_LOCK_Handler handler, FMT_LOCK_Cleanup cleanup)
Create a new MT lock (with an internal reference count set to 1).
Definition: ncbi_core.c:199
EIO_WriteMethod
I/O write method.
Definition: ncbi_core.h:99
const char * message
Definition: ncbi_core.h:340
LOG LOG_Reset(LOG lg, void *data, FLOG_Handler handler, FLOG_Cleanup cleanup)
Reset the "lg" to use the new "data", "handler" and "cleanup".
Definition: ncbi_core.c:333
const char * LOG_LevelStr(ELOG_Level level)
Obtain verbal representation of an enum level value.
Definition: ncbi_core.c:294
EIO_Event
I/O event (or direction).
Definition: ncbi_core.h:118
void(* FREG_Cleanup)(void *data)
Registry cleanup callback.
Definition: ncbi_core.h:604
REG REG_AddRef(REG rg)
Increment internal reference count by 1, then return "rg".
Definition: ncbi_core.c:528
LOG LOG_Delete(LOG lg)
Decrement internal reference count by 1, and if it reaches 0, then call "lg->cleanup(lg->data)",...
Definition: ncbi_core.c:365
void(* FMT_LOCK_Cleanup)(void *data)
MT lock cleanup callback.
Definition: ncbi_core.h:216
void(* FLOG_Cleanup)(void *data)
Log cleanup callback.
Definition: ncbi_core.h:375
int REG_Set(REG rg, const char *section, const char *name, const char *value, EREG_Storage storage)
Store the "value" into the registry section "section" under the key "name", and according to "storage...
Definition: ncbi_core.c:605
@ eLOG_Critical
Definition: ncbi_core.h:298
@ eLOG_Error
Definition: ncbi_core.h:297
@ eLOG_Note
Definition: ncbi_core.h:294
@ eLOG_Info
In C++ Toolkit "Info" is used, not "Note".
Definition: ncbi_core.h:295
@ eLOG_Warning
Definition: ncbi_core.h:296
@ eLOG_Trace
Definition: ncbi_core.h:293
@ eLOG_Fatal
Definition: ncbi_core.h:299
@ eMT_Unlock
unlock critical section
Definition: ncbi_core.h:183
@ eMT_Lock
lock critical section
Definition: ncbi_core.h:181
@ eMT_LockRead
lock critical section for reading
Definition: ncbi_core.h:182
@ eMT_TryLock
try to lock, return immediately
Definition: ncbi_core.h:184
@ eMT_TryLockRead
try to lock for reading, return immediately
Definition: ncbi_core.h:185
@ eREG_Transient
only in-memory storage while program runs
Definition: ncbi_core.h:529
@ eREG_Persistent
hard-copy storage across program runs
Definition: ncbi_core.h:530
@ eIO_Timeout
timeout expired before any I/O succeeded
Definition: ncbi_core.h:134
@ eIO_Interrupt
signal arrival prevented any I/O to succeed
Definition: ncbi_core.h:136
@ eIO_NotSupported
operation is not supported or is not available
Definition: ncbi_core.h:138
@ eIO_Success
everything is fine, no error occurred
Definition: ncbi_core.h:133
@ eIO_Reserved
reserved status code – DO NOT USE!
Definition: ncbi_core.h:135
@ eIO_Unknown
unknown I/O error (likely fatal but can retry)
Definition: ncbi_core.h:139
@ eIO_InvalidArg
bad argument / parameter value(s) supplied
Definition: ncbi_core.h:137
@ eIO_ReadPlain
read readily available data only, wait if none
Definition: ncbi_core.h:90
@ eIO_ReadPeek
do eIO_ReadPlain but leave data in input queue
Definition: ncbi_core.h:89
@ eIO_ReadPersist
read exactly as much as requested, w/waits
Definition: ncbi_core.h:91
@ eIO_WritePlain
write as much as possible, report back how much
Definition: ncbi_core.h:101
@ eIO_WriteOutOfBand
write out-of-band chunk of urgent data (if supp)
Definition: ncbi_core.h:103
@ eIO_WriteNone
invalid reserved opcode, not for use!
Definition: ncbi_core.h:100
@ eIO_WritePersist
write exactly as much as specified, w/waits
Definition: ncbi_core.h:102
@ eIO_Write
write
Definition: ncbi_core.h:121
@ eIO_ReadWrite
eIO_Read | eIO_Write (also, eCONN_OnFlush)
Definition: ncbi_core.h:122
@ eIO_Open
also serves as no-event indicator in SOCK_Poll
Definition: ncbi_core.h:119
@ eIO_Close
also serves as an error indicator in SOCK_Poll
Definition: ncbi_core.h:123
@ eIO_Read
read
Definition: ncbi_core.h:120
#define NCBI_XCONNECT_EXPORT
unsigned int
A callback function used to compare two keys in a database.
Definition: types.hpp:1210
FILE * file
const GenericPointer< typename T::ValueType > T2 value
Definition: pointer.h:1227
MT_LOCK lock
Definition: ncbi_core.c:478
FREG_Get get
Definition: ncbi_core.c:475
Message and miscellaneous data to pass to log post callback FLOG_Handler.
Definition: ncbi_core.h:338
Definition: inftrees.h:24
Modified on Sat May 25 14:21:38 2024 by modify_doxy.py rev. 669887