1DC_SERVER_NEW(2) distcache DC_SERVER_NEW(2)
2
6 DC_SERVER_set_default_cache, DC_SERVER_set_cache, DC_SERVER_new,
7 DC_SERVER_free, DC_SERVER_items_stored, DC_SERVER_reset_operations,
8 DC_SERVER_num_operations, DC_SERVER_new_client, DC_SERVER_del_client,
9 DC_SERVER_process_client, DC_SERVER_clients_to_sel,
10 DC_SERVER_clients_io - distcache server API
11
13 #include <distcache/dc_server.h>
14 DC_SERVER *DC_SERVER_new(unsigned int max_sessions);
16 void DC_SERVER_free(DC_SERVER *ctx);
17 int DC_SERVER_set_default_cache(void);
18 int DC_SERVER_set_cache(const DC_CACHE_cb *impl);
19 unsigned int DC_SERVER_items_stored(DC_SERVER *ctx,
20 const struct timeval *now);
21 void DC_SERVER_reset_operations(DC_SERVER *ctx);
22 unsigned long DC_SERVER_num_operations(DC_SERVER *ctx);
23 DC_CLIENT *DC_SERVER_new_client(DC_SERVER *ctx, NAL_CONNECTION *conn,
24 unsigned int flags);
25 int DC_SERVER_del_client(DC_CLIENT *clnt);
26 int DC_SERVER_process_client(DC_CLIENT *clnt,
27 const struct timeval *now);
28 int DC_SERVER_clients_to_sel(DC_SERVER *ctx, NAL_SELECTOR *sel);
29 int DC_SERVER_clients_io(DC_SERVER *ctx, NAL_SELECTOR *sel,
30 const struct timeval *now);
31
33 DC_SERVER_new() returns an initialised DC_SERVER object, or NULL for
34 failure.
35 DC_SERVER_free() and DC_SERVER_reset_operations() have no return value.
37 DC_SERVER_items_stored() returns the number of cached sessions in a
39 cache (after any session expiry is performed).
40 DC_SERVER_num_operations() indicates how many operations the cache
42 object has performed.
43 DC_SERVER_new_client() returns a new DC_CLIENT object, or NULL for
45 failure.
46 The remaining functions return non-zero for success or zero for fail‐
48 ure.
49
51 Use of the dc_server.h header requires the "struct timeval" type to be
52 defined. On many systems, this will require that you include the time.h
53 header in advance, though details will vary from system to system. If
54 in doubt, try consulting your system's gettimeofday(2) man page for
55 information on how to have this system type defined.
56 These DC_SERVER functions facilitate the implementation a session cache
58 server to be compatible with the distcache protocol. The source code to
59 dc_server(1) provides an example of using this API, and is probably the
60 ideal reference (a single C file of 304 lines). The storage of the
61 cache is provided by a table of handler functions defined by the
62 DC_CACHE_cb structure;
63 typedef struct st_DC_CACHE_cb {
65 DC_CACHE * (*cache_new)(unsigned int max_sessions);
66 void (*cache_free)(DC_CACHE *cache);
67 int (*cache_add)(DC_CACHE *cache,
68 const struct timeval *now,
69 unsigned long timeout_msecs,
70 const unsigned char *session_id,
71 unsigned int session_id_len,
72 const unsigned char *data,
73 unsigned int data_len);
74 unsigned int (*cache_get)(DC_CACHE *cache,
75 const struct timeval *now,
76 const unsigned char *session_id,
77 unsigned int session_id_len,
78 unsigned char *store,
79 unsigned int store_size);
80 int (*cache_remove)(DC_CACHE *cache,
81 const struct timeval *now,
82 const unsigned char *session_id,
83 unsigned int session_id_len);
84 int (*cache_have)(DC_CACHE *cache,
85 const struct timeval *now,
86 const unsigned char *session_id,
87 unsigned int session_id_len);
88 unsigned int (*cache_num_items)(DC_CACHE *cache,
89 const struct timeval *now);
90 } DC_CACHE_cb;
91 libdistcacheserver provides a default implementation that can be
93 enabled by calling DC_SERVER_set_default_cache() prior to
94 DC_SERVER_new(). Alternatively, a customised cache implementation can
95 be specified by DC_SERVER_set_cache(). The reason that one or the
96 other must be specified is so that custom implementations will not need
97 to have the default implementation linked in because they won't explic‐
98 itly call DC_SERVER_set_default_cache().
99 The choice of DC_CACHE_cb implementation will control all manipulations
101 and queries on the session cache. Each handler is passed a struct
102 timeval value to allow it to implicitly handle expiry of old sessions
103 without having to repeatedly query the time on each invokation.
104 Outside the actual cache implementation, the other subject covered by
106 libdistcacheserver is that of managing client connections and process‐
107 ing their requests. It is assumed that the caller will use libnal to
108 handle the network aspects of the cache server - otherwise the applica‐
109 tion would be better to use the lower-level DC_PLUG API (see
110 DC_PLUG_new(2)), and the implementation of libdistcacheserver would
111 provide a good reference for this.
112 New clients of the cache server are created by DC_SERVER_new_client()
114 using the supplied connection object conn. The behaviour of the
115 returned DC_CLIENT object depends on the flags parameter, which is zero
116 or a bitwise combination of the following values;
117 #define DC_CLIENT_FLAG_NOFREE_CONN (unsigned int)0x0001
119 #define DC_CLIENT_FLAG_IN_SERVER (unsigned int)0x0002
120 If DC_CLIENT_FLAG_NOFREE_CONN is set, then conn will not be destroyed
122 when the DC_CLIENT object is destroyed by DC_SERVER_new_client(). Note,
123 the DC_CLIENT object encapsulates the provided conn object and does not
124 copy it.
125 If DC_CLIENT_FLAG_IN_SERVER is set, then network traffic and request
127 processing for the client will be implicit in the
128 DC_SERVER_clients_to_sel() and DC_SERVER_clients_io() functions. This
129 includes destroying any clients that have disconnected at the network
130 level or had corruption errors at the data level.
131 If DC_CLIENT_FLAG_IN_SERVER is not set, then selecting and performing
133 network I/O should be handled by the caller directly using the original
134 conn object, and checking for (and processing of) requests should be
135 handled directly by DC_SERVER_process_client(). A zero return value
136 from this function indicates an error in the client's processing, and
137 would then require the caller to destroy the client object via
138 DC_SERVER_del_client(). This allows network handling and logical cache
139 handling to be explicitly separated by the implementation if required.
140 Note that the dc_server(1) implementation is greatly simplified by
142 using DC_CLIENT_FLAG_IN_SERVER and not setting
143 DC_CLIENT_FLAG_NOFREE_CONN. This allows it to forget about NAL_CONNEC‐
144 TION objects after they have been successfully converted into DC_CLIENT
145 objects, and in fact can forget about the resulting DC_CLIENT objects
146 too as they become completely controlled by the DC_SERVER object. If
147 the client is closed, the underlying connection object is destroyed
148 also. If the cache server itself is destroyed, then any remaining
149 clients will likewise be properly cleaned up.
150 DC_SERVER_clients_to_sel() and DC_SERVER_clients_io() only operate on
152 cache clients that are created with the DC_CLIENT_FLAG_IN_SERVER flag.
153
155 DC_PLUG_new(2), DC_PLUG_read(2) - Lower-level asynchronous implementa‐
156 tion of the distcache protocol, useful for client and server operation.
157 dc_server(1) - Runs a cache server listening on a configurable network
159 address.
160 distcache(8) - Overview of the distcache architecture.
162 http://www.distcache.org/ - Distcache home page.
164
166 This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
167 graphic Appliances Incorporated. Since the project was released into
168 open source, it has a home page and a project environment where devel‐
169 opment, mailing lists, and releases are organised. For problems with
170 the software or this man page please check for new releases at the
171 project web-site below, mail the users mailing list described there, or
172 contact the author at geoff@geoffthorpe.net.
173 Home Page: http://www.distcache.org
1751.4.5 2004.03.23 DC_SERVER_NEW(2)