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

Go to the SVN repository for this file.

1 #ifndef CONNECT___NCBI_SERVICE__H
2 #define CONNECT___NCBI_SERVICE__H
3 
4 /* $Id: ncbi_service.h 98086 2022-09-27 18:56:33Z 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  * Authors: Anton Lavrentiev, Denis Vakatov
30  *
31  * File Description:
32  * @file ncbi_service.h
33  * Top-level API to resolve NCBI service names into server meta-addresses.
34  *
35  */
36 
38 #include <connect/ncbi_host_info.h>
39 
40 
41 /** @addtogroup ServiceSupport
42  *
43  * @{
44  */
45 
46 /** Revision 7.0 */
47 #define SERV_CLIENT_REVISION_MAJOR 7
48 #define SERV_CLIENT_REVISION_MINOR 0
49 
50 /** Special values for the "preferred_host" parameter.
51  * @sa
52  * SERV_OpenEx, SERV_GetInfoEx
53  */
54 #define SERV_LOCALHOST ((unsigned int)(~0UL))
55 #define SERV_ANYHOST 0
56 
57 
58 #ifdef __cplusplus
59 extern "C" {
60 #endif
61 
62 
63 /* Fwdecl of an opaque type */
64 struct SSERV_IterTag;
65 /** Iterator through the servers */
66 typedef struct SSERV_IterTag* SERV_ITER;
67 
68 
69 /** Simplified (uncluttered) SSERV_Info pointer type */
70 typedef const SSERV_Info* SSERV_InfoCPtr;
71 
72 
73 /** Special "type" bit values that may be combined with server types.
74  * @note MSW should be maintained compatible with EMGHBN_Option.
75  * @sa
76  * ESERV_Type, ESERV_OpenEx, SERV_GetInfoEx
77  */
79  fSERV_Any = 0,
80  fSERV_All = 0x00007FFF, /**< Server type mask */
81  fSERV_Stateless = 0x00008000, /**< Stateless servers only */
82  fSERV_Reserved = 0x00100000, /**< Reserved, MBZ */
83  fSERV_DelayOpen = 0x00400000, /**< Don't open service until use */
84  fSERV_ReverseDns = 0x00800000, /**< LB-DNS translation */
85  /* The following allow to get otherwise excluded service instances */
86  fSERV_IncludeDown = 0x08000000,
87  fSERV_IncludeStandby = 0x10000000,
88  fSERV_IncludeReserved = 0x20000000, /**< @note Not yet implemented */
90  fSERV_IncludeInactive = 0x70000000,
91  fSERV_IncludePrivate = 0x80000000,
92  fSERV_Promiscuous = 0xF8000000 /**< Evrthng and the kitchen sink */
93 };
94 typedef unsigned int TSERV_Type; /**<Bitwise OR of ESERV_Type[Special]*/
95 typedef unsigned short TSERV_TypeOnly; /**<Server type only, w/o specials */
96 
97 
98 /** Create an iterator for sequential server lookup.
99  * @note 'nbo' in comments denotes parameters coming in network byte order;
100  * 'hbo' stands for 'host byte order'.
101  * @param service
102  * A service name, may not be NULL or empty.
103  * @param types
104  * A bitset of type(s) of servers requested.
105  * @param preferred_host
106  * Preferred host to use the service at, nbo.
107  * @param net_info
108  * Connection information (NULL prevents the use of the network-based
109  * dispatching via LINKERD, NAMERD, and DISPD)
110  * @note If "net_info" is NULL, only the following mappers will be consulted:
111  * LOCAL(if enabled, see below), LBSMD, and LBDNS.
112  * If "net_info" is not NULL, the above mappers are consulted first,
113  * followed by
114  * LINKERD, NAMERD, and DISPD
115  * (using the connection information provided) but only if mapping with
116  * the preceding mapper(s), if any occurred, has failed.
117  * @note The registry section [CONN], keys:
118  * LOCAL_ENABLE, LBSMD_DISABLE, LBDNS_ENABLE, LINKERD_ENABLE,
119  * NAMERD_ENABLE, DISPD_DISABLE
120  * which can be overridden by the environment variables:
121  * CONN_LOCAL_ENABLE, CONN_LBSMD_DISABLE, CONN_LBDNS_ENABLE,
122  * CONN_LINKERD_ENABLE, CONN_NAMERD_ENABLE, and CONN_DISPD_DISABLE
123  * can be used to add(for LOCAL, LBDNS, LINKERD, NAMERD) or to skip (for
124  * LBSMD and DISPD) the corresponding service mapper(s). This scheme
125  * permits to use any combination of the service mappers (local/lbsmd/
126  * lbdns/linkerd/namerd/dispd, network-aware or not).
127  * These keys can also be used for even more granular, per-service basis,
128  * as described in <connect/ncbi_connutil.h> -- when used in the registry
129  * section '[service]' or prefixed with the service name in the process
130  * environment.
131  * @note If "net_info" is not NULL then a non-zero value of
132  * "net_info->stateless" forces "types" to get the "fSERV_Stateless" bit
133  * set implicitly.
134  * @param skip
135  * An array of servers NOT to select: contains server-info elements that are
136  * not to return from the search (whose server-infos match the would-be
137  * result).
138  * @note However, special additional rules apply to the "skip" elements when
139  * the fSERV_ReverseDns bit is set in the "types" parameter: the
140  * result-to-be is not considered if either
141  * 1. There is an entry of the fSERV_Dns type found in "skip" array that
142  * matches the host[:port] (any port if the skip entry's port is 0); or
143  * 2. The reverse lookup of the host:port turns up an fSERV_Dns-type server
144  * whose name matches an fSERV_Dns-type server in "skip".
145  * @param n_skip
146  * Number of entries in the "skip" array.
147  * @return
148  * Non-NULL iterator, or NULL if the service does not exist.
149  * @note
150  * Non-NULL iterator does not guarantee the service operational, it merely
151  * acknowledges the service existence.
152  * @sa
153  * SERV_GetNextInfoEx, SERV_Reset, SERV_Close, ConnNetInfo_Create
154  */
156 (const char* service,
158  unsigned int preferred_host,
159  const SConnNetInfo* net_info,
160  SSERV_InfoCPtr skip[],
161  size_t n_skip
162  );
163 
164 /** Same as "SERV_OpenEx(., ., ., ., 0, 0)" -- i.e. w/o the "skip" array.
165  * @sa
166  * SERV_OpenEx
167  */
169 (const char* service,
171  unsigned int preferred_host,
172  const SConnNetInfo* net_info
173 );
174 
175 
176 /** Allocate an iterator and consult either local databases (if any present),
177  * or network database, using all default communication parameters found both
178  * in the registry and the environment variables (as if having an implicit
179  * parameter "net_info" created with "ConnNetInfo_Create(service)").
180  * @note No preferred host is set in the target iterator.
181  * @param service
182  * A service name (may not be NULL or empty).
183  * @return
184  * Non-NULL iterator, or NULL if the service does not exist.
185  * @note
186  * Non-NULL iterator does not guarantee the service operational, it merely
187  * acknowledges the service existence.
188  * @sa
189  * SERV_GetNextInfoEx, SERV_OpenEx, SERV_Reset, SERV_Close, ConnNetInfo_Create
190  */
192 (const char* service
193  );
194 
195 
196 /** Get the next server meta-address, optionally accompanied by the host
197  * parameters made available by the LB daemon (LBSMD).
198  * @param iter
199  * An iterator handle obtained via a "SERV_Open*" call.
200  * @note NULL is accepted, and results in NULL returned.
201  * @param host_info
202  * An optional pointer to store host info at (may be NULL).
203  * @return
204  * NULL if no more servers have been found for the service requested (the
205  * pointer to "host_info" remains untouched in this case); otherwise, a
206  * non-NULL pointer to the server meta address.
207  * @note The returned server-info is valid only until either of the two events:
208  * 1. SERV_GetNextInfo[Ex]() is called with this iterator again; or
209  * 2. The iterator reset / closed (SERV_Reset() / SERV_Close() called).
210  * @note Application program should NOT destroy the returned server-info as it
211  * is managed automatically by the iterator.
212  * @note Resulting DNS-type server-info (only if coming out for the first time)
213  * may contain 0 in the host field to denote that the name exists but the
214  * service is currently not serving (down / unavailable).
215  * @note Only when completing successfully, i.e. returning a non-NULL info,
216  * this call can also provide host information as the following: if
217  * "host_info" parameter is passed as a non-NULL pointer, then a copy of
218  * host information may be allocated, and the handle is then stored at
219  * "*host_info" when the host information is available for the host.
220  * Otherwise, the pointer is updated with a NULL value stored. Using the
221  * non-NULL handle returned, various parameters like load, environment,
222  * number of CPUs, etc can be retrieved (see ncbi_host_info.h). The
223  * returned host information handle has to be explicitly free()'d when
224  * no longer needed.
225  * @sa
226  * SERV_Reset, SERV_Close, SERV_GetInfoEx, ncbi_host_info.h
227  */
229 (SERV_ITER iter,
230  HOST_INFO* host_info
231  );
232 
233 /** Same as "SERV_GetNextInfoEx(., 0)" -- i.e. w/o the host information.
234  * @sa
235  * SERV_GetNextInfoEx
236  */
238 (SERV_ITER iter
239  );
240 
241 
242 /** A "fast track" routine equivalent to creating of an iterator as with
243  * SERV_OpenEx(), and then taking an info as with SERV_GetNextInfoEx().
244  * However, this call is optimized for an application, which only needs
245  * a single entry (the first one), and which is not interested in iterating
246  * over all available instances. Both the returned server-info and host
247  * information (if any) have to be explicitly free()'d by the application when
248  * no longer needed.
249  * @param service
250  * A service name (may not be NULL or empty).
251  * @param types
252  * A bitset of type(s) of servers requested.
253  * @param preferred_host
254  * Preferred host to use the service at, nbo.
255  * @param net_info
256  * Connection information (NULL disables network-based dispatching via
257  * LINKERD, NAMERD, and DISPD)
258  * @param skip[]
259  * An array of servers NOT to select, see SERV_OpenEx() for notes.
260  * @param n_skip
261  * Number of entries in the "skip" array.
262  * @param host_info
263  * An optional pointer to store host info at (may be NULL).
264  * @note The host information is provided only (if at all) if this call returns
265  * a non-NULL result, see SERV_OpenEx() for notes.
266  * @return
267  * First matching server-info (non-NULL), or NULL if no instances found.
268  * @sa
269  * SERV_GetInfo, SERV_OpenEx
270  */
272 (const char* service,
274  unsigned int preferred_host,
275  const SConnNetInfo* net_info,
277  size_t n_skip,
278  HOST_INFO* host_info
279  );
280 
281 /** Same as "SERV_GetInfoEx(., ., ., ., 0, 0, 0)" -- i.e. w/o the "skip" array,
282  * and w/o "host_info".
283  * @sa
284  * SERV_GetInfoEx, SERV_Open
285  */
287 (const char* service,
289  unsigned int preferred_host,
290  const SConnNetInfo* net_info
291  );
292 
293 /** Equivalent to "SERV_GetInfo(., fSERV_Any, SERV_ANYHOST,
294  * ConnNetInfo_Create(service))",
295  * but it takes care not to leak its last "net_info" parameter, which it builds
296  * on the fly.
297  * @sa
298  * SERV_GetInfo, SERV_OpenSimple
299  */
301 (const char* service
302  );
303 
304 
305 /** Penalize the server returned last from SERV_GetNextInfo[Ex]().
306  * @param iter
307  * An iterator handle obtained via a "SERV_Open*" call.
308  * @param fine
309  * A fine value in the range [0=min..100=max] (%%), inclusive.
310  * @return
311  * Return 0 if failed, non-zero if successful.
312  * @sa
313  * SERV_OpenEx, SERV_GetNextInfoEx
314  */
315 extern NCBI_XCONNECT_EXPORT int/*bool*/ SERV_Penalize
316 (SERV_ITER iter,
317  double fine
318  );
319 
320 
321 /** Rerate the server returned last from SERV_GetNextInfo[Ex]().
322  * @note This is an experimental API.
323  * @param iter
324  * An iterator handle obtained via a "SERV_Open*" call.
325  * @param rate
326  * A new rate value, or 0.0 to turn the server off, or
327  * fabs(rate) >= LBSM_RERATE_DEFAULT to revert to the default.
328  * @return
329  * Return 0 if failed, non-zero if successful.
330  * @sa
331  * SERV_OpenEx, SERV_GetNextInfoEx
332  */
333 extern NCBI_XCONNECT_EXPORT int/*bool*/ SERV_Rerate
334 (SERV_ITER iter,
335  double rate
336  );
337 
338 
339 /** Reset the iterator to the state as if it has just been opened.
340  * @warning Invalidates all previosuly issued server descriptors (SSERV_Info*).
341  * @param iter
342  * An iterator handle obtained via a "SERV_Open*" call.
343  * @note NULL is accepted, and causes no actions.
344  * @sa
345  * SERV_OpenEx, SERV_GetNextInfoEx, SERV_Close
346  */
348 (SERV_ITER iter /* handle obtained via 'SERV_Open*' call*/
349  );
350 
351 
352 /** Deallocate the iterator. Must be called to finish the lookup process.
353  * @warning Invalidates all previosuly issued server descriptors (SSERV_Info*).
354  * @param iter
355  * An iterator handle obtained via a "SERV_Open*" call.
356  * @note NULL is accepted, and causes no actions.
357  * @sa
358  * SERV_OpenEx, SERV_Reset
359  */
361 (SERV_ITER iter
362  );
363 
364 
365 /** Obtain a port number that corresponds to the named (standalone) service
366  * declared at the specified host (per the LB configuration information).
367  * @param name
368  * Service name (of type fSERV_Standalone) to look up.
369  * @param host
370  * Host address (or SERV_LOCALHOST, or 0, same) to look the service up at.
371  * @return
372  * The port number or 0 on error (no suitable service found).
373  * @note The call returns the first match, and does not check whether an
374  * application is already running at the returned port (i.e. regardless
375  * of whether or not the service is currently up).
376  * @sa
377  * ESERV_Type, SERV_OpenEx, LSOCK_CreateEx
378  */
379 extern NCBI_XCONNECT_EXPORT unsigned short SERV_ServerPort
380 (const char* name,
381  unsigned int host
382  );
383 
384 
385 /** Set a server type to use when a service mapper returns typeless entries for
386  * the given service name (typed entries retain their types as received).
387  * @note Current implementation of this call tries to store the association in
388  * the application's registry as a transient setting. Only if that has
389  * failed, then it proceeds to store the association in the application
390  * environment.
391  * @note Implicit server type designation is managed the same way as any other
392  * service-related parameters from <connect/ncbi_connutil.h>: this one is
393  * using the REG_CONN_IMPLICIT_SERVER_TYPE key.
394  * @return
395  * 0 if failed; non-zero if succeeded
396  * @sa
397  * ConnNetInfo_GetValue, SERV_GetImplicitServerType
398  */
400 (const char* service,
402  );
403 
404 
405 /** Get a server type that would be assigned to typeless entries for the given
406  * service name.
407  * @sa
408  * ConnNetInfo_GetValue, SERV_SetImplicitServerType, SERV_GetImplicitServerTypeDefault
409  */
411 (const char* service
412  );
413 
414 
415 #ifdef __cplusplus
416 } /* extern "C" */
417 #endif
418 
419 
420 /* @} */
421 
422 #endif /* CONNECT___NCBI_SERVICE__H */
static const struct type types[]
Definition: type.c:22
ESERV_Type
SSERV_InfoCPtr SERV_GetNextInfo(SERV_ITER iter)
Same as "SERV_GetNextInfoEx(., 0)" – i.e.
Definition: ncbi_service.c:936
void SERV_Close(SERV_ITER iter)
Deallocate the iterator.
Definition: ncbi_service.c:993
SSERV_Info * SERV_GetInfoEx(const char *service, TSERV_Type types, unsigned int preferred_host, const SConnNetInfo *net_info, SSERV_InfoCPtr skip[], size_t n_skip, HOST_INFO *host_info)
A "fast track" routine equivalent to creating of an iterator as with SERV_OpenEx(),...
Definition: ncbi_service.c:886
SSERV_Info * SERV_GetInfoSimple(const char *service)
Equivalent to "SERV_GetInfo(., fSERV_Any, SERV_ANYHOST, ConnNetInfo_Crea...
Definition: ncbi_service.c:858
int SERV_SetImplicitServerType(const char *service, ESERV_Type type)
Set a server type to use when a service mapper returns typeless entries for the given service name (t...
ESERV_TypeSpecial
Special "type" bit values that may be combined with server types.
Definition: ncbi_service.h:78
void SERV_Reset(SERV_ITER iter)
Reset the iterator to the state as if it has just been opened.
Definition: ncbi_service.c:981
int SERV_Penalize(SERV_ITER iter, double fine)
Penalize the server returned last from SERV_GetNextInfo[Ex]().
Definition: ncbi_service.c:966
unsigned short SERV_ServerPort(const char *name, unsigned int host)
Obtain a port number that corresponds to the named (standalone) service declared at the specified hos...
struct SSERV_IterTag * SERV_ITER
Iterator through the servers.
Definition: ncbi_service.h:66
SSERV_Info * SERV_GetInfo(const char *service, TSERV_Type types, unsigned int preferred_host, const SConnNetInfo *net_info)
Same as "SERV_GetInfoEx(., ., ., ., 0, 0, 0)" – i.e.
Definition: ncbi_service.c:872
SERV_ITER SERV_OpenEx(const char *service, TSERV_Type types, unsigned int preferred_host, const SConnNetInfo *net_info, SSERV_InfoCPtr skip[], size_t n_skip)
Create an iterator for sequential server lookup.
Definition: ncbi_service.c:822
SERV_ITER SERV_Open(const char *service, TSERV_Type types, unsigned int preferred_host, const SConnNetInfo *net_info)
Same as "SERV_OpenEx(., ., ., ., 0, 0)" – i.e.
Definition: ncbi_service.c:809
unsigned int TSERV_Type
Bitwise OR of ESERV_Type[Special].
Definition: ncbi_service.h:94
unsigned short TSERV_TypeOnly
Server type only, w/o specials.
Definition: ncbi_service.h:95
int SERV_Rerate(SERV_ITER iter, double rate)
Rerate the server returned last from SERV_GetNextInfo[Ex]().
Definition: ncbi_service.c:972
ESERV_Type SERV_GetImplicitServerType(const char *service)
Get a server type that would be assigned to typeless entries for the given service name.
SERV_ITER SERV_OpenSimple(const char *service)
Allocate an iterator and consult either local databases (if any present), or network database,...
Definition: ncbi_service.c:795
const SSERV_Info * SSERV_InfoCPtr
Simplified (uncluttered) SSERV_Info pointer type.
Definition: ncbi_service.h:70
SSERV_InfoCPtr SERV_GetNextInfoEx(SERV_ITER iter, HOST_INFO *host_info)
Get the next server meta-address, optionally accompanied by the host parameters made available by the...
Definition: ncbi_service.c:928
@ fSERV_ReverseDns
LB-DNS translation.
Definition: ncbi_service.h:84
@ fSERV_IncludeSuppressed
Definition: ncbi_service.h:89
@ fSERV_IncludeInactive
Definition: ncbi_service.h:90
@ fSERV_All
Server type mask.
Definition: ncbi_service.h:80
@ fSERV_Stateless
Stateless servers only.
Definition: ncbi_service.h:81
@ fSERV_IncludeStandby
Definition: ncbi_service.h:87
@ fSERV_Reserved
Reserved, MBZ.
Definition: ncbi_service.h:82
@ fSERV_IncludeDown
Definition: ncbi_service.h:86
@ fSERV_Any
Definition: ncbi_service.h:79
@ fSERV_Promiscuous
Evrthng and the kitchen sink.
Definition: ncbi_service.h:92
@ fSERV_IncludeReserved
Definition: ncbi_service.h:88
@ fSERV_IncludePrivate
Definition: ncbi_service.h:91
@ fSERV_DelayOpen
Don't open service until use.
Definition: ncbi_service.h:83
#define NCBI_XCONNECT_EXPORT
const char * name
Definition: ncbi_servicep.h:89
SSERV_InfoCPtr * skip
unsigned int host
Definition: ncbi_servicep.h:92
Definition: type.c:6
Modified on Fri Sep 20 14:57:25 2024 by modify_doxy.py rev. 669887