NCBI C++ ToolKit
ncbi_core_cxx.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CONNECT___NCBI_CORE_CXX__H
2 #define CONNECT___NCBI_CORE_CXX__H
3 
4 /* $Id: ncbi_core_cxx.hpp 100003 2023-06-02 14:55:00Z 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: Anton Lavrentiev
30  *
31  * File description:
32  * @file ncbi_core_cxx.hpp
33  * C++->C conversion functions for basic CORE connect stuff:
34  * - Registry,
35  * - Logging,
36  * - Locking.
37  *
38  */
39 
40 #include <corelib/ncbireg.hpp>
41 #include <connect/ncbi_tls.h>
42 
43 
44 /** @addtogroup UtilityFunc
45  *
46  * @{
47  */
48 
49 
51 
52 
53 /// Convert a C++ Toolkit registry object to a REG registry.
54 /// @note The C++ registries are CObjects, so any we "own" will be deleted
55 /// if and only if nothing else is still holding a reference to them.
56 /// @param reg
57 /// A C++ toolkit registry, on top of which new REG registry is to be created
58 /// @param pass_ownership
59 /// True if the ownership of "reg" gets passed to new REG
60 /// @return
61 /// New REG registry (or NULL on error)
62 /// @sa
63 /// REG_Create, CONNECT_Init
65 (IRWRegistry* reg,
66  bool pass_ownership = false
67  );
68 
69 
70 /// Convert a C++ Toolkit read-only registry object to a REG registry.
71 /// @note The returned registry won't have a set method available, and any
72 /// attempt to set a parameter will fail.
73 /// @note The C++ registries are CObjects, so any we "own" will be deleted
74 /// if and only if nothing else is still holding a reference to them.
75 /// @param reg
76 /// A C++ toolkit registry, on top of which new REG registry is to be created
77 /// @param pass_ownership
78 /// True if the ownership of "reg" gets passed to new REG
79 /// @return
80 /// New REG registry (or NULL on error)
81 /// @sa
82 /// REG_Create, CONNECT_Init
84 (const IRWRegistry* reg,
85  bool pass_ownership = false
86  );
87 
88 
89 /// Create LOG on top of C++ Toolkit CNcbiDiag.
90 /// @return
91 /// New LOG log (or NULL on error)
92 /// @sa
93 /// LOG_Create, CONNECT_Init
95 
96 
97 /// Convert a C++ Toolkit lock object to an MT_LOCK lock.
98 /// @param lock
99 /// Existing lock to convert (if NULL a new CRWLock will be used)
100 /// @param pass_ownership
101 /// True if the ownership of non-NULL lock gets passed to new MT_LOCK
102 /// @return
103 /// New MT_LOCK lock (or NULL on error)
104 /// @sa
105 /// MT_LOCK_Create, CONNECT_Init
107 (CRWLock* lock = 0,
108  bool pass_ownership = false
109  );
110 
111 
112 /// CONNECT_Init flags: which parameters to own / initialize.
113 /// @sa
114 /// CONNECT_Init
116  eConnectInit_OwnNothing = 0, ///< Original ownership gets retained
117  eConnectInit_OwnRegistry = 1, ///< Registry ownership gets passed
118  eConnectInit_OwnLock = 2, ///< Lock ownership gets passed
119  eConnectInit_NoSSL = 4 ///< Do NOT init secure socket layer (SSL)
120 };
121 typedef unsigned int TConnectInitFlags; ///< Bitwise OR of EConnectInitFlag
122 
123 
124 /// Init [X]CONNECT library with the specified "reg" and "lock" (ownership for
125 /// either or both can be detailed in the "flag" parameter).
126 /// @warning MUST be called in MT applications to make CONNECT MT-safe, or
127 /// alternatively, CConnIniter must be used as a base-class.
128 /// @param reg
129 /// Registry to use, non-modifiable (none if NULL)
130 /// @param lock
131 /// Lock to use (new lock will get created if NULL)
132 /// @param flag
133 /// Ownership / initialization control
134 /// @param ssl
135 /// TLS provider to use for SSL (ignored if eConnectInit_NoSSL;
136 /// 0 selects the default provider)
137 /// @note LOG will get created out of CNcbiDiag automatically.
138 /// @sa
139 /// EConnectInitFlag, CConnIniter, REG_cxx2c, LOG_cxx2c, MT_LOCK_cxx2c,
140 /// NcbiSetupTls, SOCK_SetupSSL,
141 /// CNcbiApplication, CRWLock, CNcbiRegistry, CNcbiDiag
143 (const IRWRegistry* reg = 0,
144  CRWLock* lock = 0,
146  FSSLSetup ssl = 0);
147 
148 
149 /////////////////////////////////////////////////////////////////////////////
150 ///
151 /// Helper hook-up class that installs default logging/registry/locking (but
152 /// only if they have not yet been installed explicitly by the user) as if by
153 /// calling CONNECT_Init(&CNcbiApplication::GetConfig()) automagically.
154 /// @note Derive your CONNECT-dependent classes from this class for MT safety:
155 /// @code
156 /// class CMyNetworkedObject : virtual protected CConnIniter
157 /// [, ... other bases]
158 /// @endcode
159 /// @note You can also use this class for an inline initialization of some
160 /// library code (in a function body) like so:
161 /// @code
162 /// {{
163 /// class CInPlaceConnIniter : protected CConnIniter {
164 /// } conn_initer;
165 /// }}
166 /// @endcode
167 /// @sa
168 /// CONNECT_Init, CConn_IOStream, CONN_OpenURL
170 {
171 protected:
172  CConnIniter(void);
173 };
174 
175 
176 
177 /////////////////////////////////////////////////////////////////////////////
178 ///
179 /// CTimeout/STimeout adapters
180 ///
181 
182 /// Convert CTimeout to STimeout.
183 ///
184 /// @param cto
185 /// Timeout value to convert.
186 /// @param sto
187 /// Variable to receive a numeric timeout value.
188 /// @return
189 /// A special constant kDefaultTimeout or kInfiniteTimeout, if the incoming
190 /// timeout is either a default or an infinite one, respectively.
191 /// A pointer to the "sto" variable, if the incoming timeout contains some
192 /// other (finite and numeric) value, and "sto" is used to receive the value.
193 /// @sa CTimeout, STimeout
194 const STimeout* g_CTimeoutToSTimeout(const CTimeout& cto, STimeout& sto);
195 
196 /// Convert STimeout to CTimeout.
197 ///
198 /// @sa CTimeout, STimeout
200 
201 
202 inline
204 {
205  if ( cto.IsDefault() )
206  return kDefaultTimeout;
207  if ( cto.IsInfinite() )
208  return kInfiniteTimeout;
209  ::memset(&sto, 0, sizeof(sto));
210  cto.Get(&sto.sec, &sto.usec);
211  return &sto;
212 }
213 
214 inline
216 {
217  if ( sto == kDefaultTimeout )
219  if ( sto == kInfiniteTimeout )
221  return CTimeout(sto->sec, sto->usec);
222 }
223 
224 
226 
227 
228 /* @} */
229 
230 #endif // CONNECT___NCBI_CORE_CXX__HPP
Helper hook-up class that installs default logging/registry/locking (but only if they have not yet be...
CRWLock –.
Definition: ncbimtx.hpp:953
CTimeout – Timeout interval.
Definition: ncbitime.hpp:1693
IRWRegistry –.
Definition: ncbireg.hpp:407
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
SOCKSSL(* FSSLSetup)(void)
SSL setup callback.
Definition: ncbi_socket.h:2312
bool IsInfinite() const
Definition: ncbitime.hpp:2729
bool IsDefault() const
Definition: ncbitime.hpp:2723
void Get(unsigned int *sec, unsigned int *microsec) const
Get timeout in seconds and microseconds.
Definition: ncbitime.cpp:3545
@ eDefault
Default timeout (to be interpreted by the client code)
Definition: ncbitime.hpp:1698
@ eInfinite
Infinite timeout.
Definition: ncbitime.hpp:1699
LOG LOG_cxx2c(void)
Create LOG on top of C++ Toolkit CNcbiDiag.
EConnectInitFlag
CONNECT_Init flags: which parameters to own / initialize.
REG REG_cxx2c(IRWRegistry *reg, bool pass_ownership=false)
Convert a C++ Toolkit registry object to a REG registry.
#define kInfiniteTimeout
Definition: ncbi_types.h:82
void CONNECT_Init(const IRWRegistry *reg=0, CRWLock *lock=0, TConnectInitFlags flag=eConnectInit_OwnNothing, FSSLSetup ssl=0)
Init [X]CONNECT library with the specified "reg" and "lock" (ownership for either or both can be deta...
const STimeout * g_CTimeoutToSTimeout(const CTimeout &cto, STimeout &sto)
CTimeout/STimeout adapters.
MT_LOCK MT_LOCK_cxx2c(CRWLock *lock=0, bool pass_ownership=false)
Convert a C++ Toolkit lock object to an MT_LOCK lock.
unsigned int usec
microseconds (modulo 1,000,000)
Definition: ncbi_types.h:78
unsigned int TConnectInitFlags
Bitwise OR of EConnectInitFlag.
unsigned int sec
seconds
Definition: ncbi_types.h:77
CTimeout g_STimeoutToCTimeout(const STimeout *sto)
Convert STimeout to CTimeout.
#define kDefaultTimeout
Definition: ncbi_types.h:81
@ eConnectInit_OwnLock
Lock ownership gets passed.
@ eConnectInit_NoSSL
Do NOT init secure socket layer (SSL)
@ eConnectInit_OwnRegistry
Registry ownership gets passed.
@ eConnectInit_OwnNothing
Original ownership gets retained.
#define NCBI_XCONNECT_EXPORT
Process information in the NCBI Registry, including working with configuration files.
Timeout structure.
Definition: ncbi_types.h:76
Modified on Sun Jun 23 05:18:54 2024 by modify_doxy.py rev. 669887