.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' .\" expand to `' in nroff, nothing in troff, for use with C<>. .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "DC_SERVER_NEW 2" .TH DC_SERVER_NEW 2 "2004.03.23" "1.4.5" "distcache" .SH "NAME" DC_SERVER_set_default_cache, DC_SERVER_set_cache, DC_SERVER_new, DC_SERVER_free, DC_SERVER_items_stored, DC_SERVER_reset_operations, DC_SERVER_num_operations, DC_SERVER_new_client, DC_SERVER_del_client, DC_SERVER_process_client, DC_SERVER_clients_to_sel, DC_SERVER_clients_io \- distcache server API .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include .Ve .PP .Vb 16 \& DC_SERVER *DC_SERVER_new(unsigned int max_sessions); \& void DC_SERVER_free(DC_SERVER *ctx); \& int DC_SERVER_set_default_cache(void); \& int DC_SERVER_set_cache(const DC_CACHE_cb *impl); \& unsigned int DC_SERVER_items_stored(DC_SERVER *ctx, \& const struct timeval *now); \& void DC_SERVER_reset_operations(DC_SERVER *ctx); \& unsigned long DC_SERVER_num_operations(DC_SERVER *ctx); \& DC_CLIENT *DC_SERVER_new_client(DC_SERVER *ctx, NAL_CONNECTION *conn, \& unsigned int flags); \& int DC_SERVER_del_client(DC_CLIENT *clnt); \& int DC_SERVER_process_client(DC_CLIENT *clnt, \& const struct timeval *now); \& int DC_SERVER_clients_to_sel(DC_SERVER *ctx, NAL_SELECTOR *sel); \& int DC_SERVER_clients_io(DC_SERVER *ctx, NAL_SELECTOR *sel, \& const struct timeval *now); .Ve .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fIDC_SERVER_new()\fR returns an initialised \fB\s-1DC_SERVER\s0\fR object, or \s-1NULL\s0 for failure. .PP \&\fIDC_SERVER_free()\fR and \fIDC_SERVER_reset_operations()\fR have no return value. .PP \&\fIDC_SERVER_items_stored()\fR returns the number of cached sessions in a cache (after any session expiry is performed). .PP \&\fIDC_SERVER_num_operations()\fR indicates how many operations the cache object has performed. .PP \&\fIDC_SERVER_new_client()\fR returns a new \fB\s-1DC_CLIENT\s0\fR object, or \s-1NULL\s0 for failure. .PP The remaining functions return non-zero for success or zero for failure. .SH "DESCRIPTION and NOTES" .IX Header "DESCRIPTION and NOTES" Use of the \fBdc_server.h\fR header requires the "\fIstruct timeval\fR" type to be defined. On many systems, this will require that you include the \fBtime.h\fR header in advance, though details will vary from system to system. If in doubt, try consulting your system's \fIgettimeofday\fR\|(2) man page for information on how to have this system type defined. .PP These \fB\s-1DC_SERVER\s0\fR functions facilitate the implementation a session cache server to be compatible with the distcache protocol. The source code to \&\fIdc_server\fR\|(1) provides an example of using this \s-1API\s0, and is probably the ideal reference (a single C file of 304 lines). The storage of the cache is provided by a table of handler functions defined by the \fBDC_CACHE_cb\fR structure; .PP .Vb 27 \& typedef struct st_DC_CACHE_cb { \& DC_CACHE * (*cache_new)(unsigned int max_sessions); \& void (*cache_free)(DC_CACHE *cache); \& int (*cache_add)(DC_CACHE *cache, \& const struct timeval *now, \& unsigned long timeout_msecs, \& const unsigned char *session_id, \& unsigned int session_id_len, \& const unsigned char *data, \& unsigned int data_len); \& unsigned int (*cache_get)(DC_CACHE *cache, \& const struct timeval *now, \& const unsigned char *session_id, \& unsigned int session_id_len, \& unsigned char *store, \& unsigned int store_size); \& int (*cache_remove)(DC_CACHE *cache, \& const struct timeval *now, \& const unsigned char *session_id, \& unsigned int session_id_len); \& int (*cache_have)(DC_CACHE *cache, \& const struct timeval *now, \& const unsigned char *session_id, \& unsigned int session_id_len); \& unsigned int (*cache_num_items)(DC_CACHE *cache, \& const struct timeval *now); \& } DC_CACHE_cb; .Ve .PP libdistcacheserver provides a default implementation that can be enabled by calling \fIDC_SERVER_set_default_cache()\fR prior to \fIDC_SERVER_new()\fR. Alternatively, a customised cache implementation can be specified by \fIDC_SERVER_set_cache()\fR. The reason that one or the other \fImust\fR be specified is so that custom implementations will not need to have the default implementation linked in because they won't explicitly call \fIDC_SERVER_set_default_cache()\fR. .PP The choice of \fBDC_CACHE_cb\fR implementation will control all manipulations and queries on the session cache. Each handler is passed a \fBstruct timeval\fR value to allow it to implicitly handle expiry of old sessions without having to repeatedly query the time on each invokation. .PP Outside the actual cache implementation, the other subject covered by \&\fIlibdistcacheserver\fR is that of managing client connections and processing their requests. It is assumed that the caller will use \fIlibnal\fR to handle the network aspects of the cache server \- otherwise the application would be better to use the lower-level \fB\s-1DC_PLUG\s0\fR \s-1API\s0 (see \fIDC_PLUG_new\fR\|(2)), and the implementation of \&\fIlibdistcacheserver\fR would provide a good reference for this. .PP New clients of the cache server are created by \fIDC_SERVER_new_client()\fR using the supplied connection object \fBconn\fR. The behaviour of the returned \fB\s-1DC_CLIENT\s0\fR object depends on the \fBflags\fR parameter, which is zero or a bitwise combination of the following values; .PP .Vb 2 \& #define DC_CLIENT_FLAG_NOFREE_CONN (unsigned int)0x0001 \& #define DC_CLIENT_FLAG_IN_SERVER (unsigned int)0x0002 .Ve .PP If \fB\s-1DC_CLIENT_FLAG_NOFREE_CONN\s0\fR is set, then \fBconn\fR will not be destroyed when the \fB\s-1DC_CLIENT\s0\fR object is destroyed by \fIDC_SERVER_new_client()\fR. Note, the \&\fB\s-1DC_CLIENT\s0\fR object encapsulates the provided \fBconn\fR object and does not copy it. .PP If \fB\s-1DC_CLIENT_FLAG_IN_SERVER\s0\fR is set, then network traffic and request processing for the client will be implicit in the \fIDC_SERVER_clients_to_sel()\fR and \fIDC_SERVER_clients_io()\fR functions. This includes destroying any clients that have disconnected at the network level or had corruption errors at the data level. .PP If \fB\s-1DC_CLIENT_FLAG_IN_SERVER\s0\fR is not set, then selecting and performing network I/O should be handled by the caller directly using the original \fBconn\fR object, and checking for (and processing of) requests should be handled directly by \fIDC_SERVER_process_client()\fR. A zero return value from this function indicates an error in the client's processing, and would then require the caller to destroy the client object via \fIDC_SERVER_del_client()\fR. This allows network handling and logical cache handling to be explicitly separated by the implementation if required. .PP Note that the \fIdc_server\fR\|(1) implementation is greatly simplified by using \&\fB\s-1DC_CLIENT_FLAG_IN_SERVER\s0\fR and not setting \fB\s-1DC_CLIENT_FLAG_NOFREE_CONN\s0\fR. This allows it to forget about \fB\s-1NAL_CONNECTION\s0\fR objects after they have been successfully converted into \fB\s-1DC_CLIENT\s0\fR objects, and in fact can forget about the resulting \fB\s-1DC_CLIENT\s0\fR objects too as they become completely controlled by the \fB\s-1DC_SERVER\s0\fR object. If the client is closed, the underlying connection object is destroyed also. If the cache server itself is destroyed, then any remaining clients will likewise be properly cleaned up. .PP \&\fIDC_SERVER_clients_to_sel()\fR and \fIDC_SERVER_clients_io()\fR only operate on cache clients that are created with the \fB\s-1DC_CLIENT_FLAG_IN_SERVER\s0\fR flag. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIDC_PLUG_new\fR\|(2), \fIDC_PLUG_read\fR\|(2) \- Lower-level asynchronous implementation of the distcache protocol, useful for client and server operation. .PP \&\fIdc_server\fR\|(1) \- Runs a cache server listening on a configurable network address. .PP \&\fIdistcache\fR\|(8) \- Overview of the distcache architecture. .PP \&\fIhttp://www.distcache.org/\fR \- Distcache home page. .SH "AUTHOR" .IX Header "AUTHOR" This toolkit was designed and implemented by Geoff Thorpe for Cryptographic Appliances Incorporated. Since the project was released into open source, it has a home page and a project environment where development, mailing lists, and releases are organised. For problems with the software or this man page please check for new releases at the project web-site below, mail the users mailing list described there, or contact the author at \fIgeoff@geoffthorpe.net\fR. .PP Home Page: \fIhttp://www.distcache.org\fR