source: project/wiki/eggref/4/memcached @ 37650

Last change on this file since 37650 was 37650, checked in by iraikov, 7 weeks ago

added zmq doc

File size: 6.2 KB
Line 
1[[tags: eggs]]
2[[toc:]]
3
4== memcached
5
6=== Description
7
8The {{memcached}} library contains procedures that implement the
9client side of the Memcached protocol. [[http://memcached.org/|Memcached]] is
10a distributed in-memory key-value store for small chunks of arbitrary data.
11
12The Chicken {{memcached}} library uses the {{base64-encode}} procedure
13from the [[base64]] library to compute hashes for given key objects,
14and the {{read}} and {{write}} procedures to store Scheme objects in a
15Memcached instance.
16
17=== Library procedures
18
19
20<procedure>(connect HOST PORT)</procedure>
21
22Connects to the Memcached server instance running on {{HOST}} at
23{{PORT}}. Returns a server handle object (see below).
24
25<procedure>(disconnect H)</procedure>
26
27Disconnects the given server handle from its host.
28
29<procedure>(stats H)</procedure>
30
31Invokes the statistics command on the server indicated by handle
32{{H}}. Returns an alist of statistics information.
33
34<procedure>(set H KEY VAL [HASH])</procedure>
35
36Set storage command on the server indicated by handle {{H}}.  {{KEY}}
37and {{VAL}} can be any serializable Scheme object.  The hash value for
38{{KEY}} is obtained by the {{HASH}} procedure, which defaults to the
39one provided by the Chicken SRFI-69 implementation. Returns {{#t}} on
40success, {{#f}} otherwise.
41
42<procedure>(add H KEY VAL [HASH])</procedure>
43
44Add storage command on the server indicated by handle {{H}}.  {{KEY}}
45and {{VAL}} can be any serializable Scheme object.  The hash value for
46{{KEY}} is obtained by the {{HASH}} procedure, which defaults to the
47one provided by the Chicken SRFI-69 implementation. Returns {{#t}} on
48success, {{#f}} otherwise.
49
50<procedure>(replace H KEY VAL [HASH])</procedure>
51
52Replace storage command on the server indicated by handle {{H}}.  {{KEY}}
53and {{VAL}} can be any serializable Scheme object.  The hash value for
54{{KEY}} is obtained by the {{HASH}} procedure, which defaults to the
55one provided by the Chicken SRFI-69 implementation. Returns {{#t}} on
56success, {{#f}} otherwise.
57
58<procedure>(get H KEY [HASH])</procedure>
59
60Get command on the server indicated by handle {{H}}. The hash value
61for {{KEY}} is obtained by the {{HASH}} procedure, which defaults to
62the one provided by the Chicken SRFI-69 implementation. Returns the
63deserialized object if the key is found, {{#f}} otherwise.
64
65<procedure>(get H KEY [HASH])</procedure>
66
67Delete command on the server indicated by handle {{H}}. The hash value
68for {{KEY}} is obtained by the {{HASH}} procedure, which defaults to
69the one provided by the Chicken SRFI-69 implementation. Returns {{#t}}
70on success,  {{#f}} otherwise.
71
72<procedure>(incr H KEY DELTA [HASH])</procedure>
73
74Increment key command on the server indicated by handle {{H}}. The
75hash value for {{KEY}} is obtained by the {{HASH}} procedure, which
76defaults to the one provided by the Chicken SRFI-69
77implementation. Returns {{#t}} on success, {{#f}} otherwise.
78
79<procedure>(decr H KEY DELTA [HASH])</procedure>
80
81Decrement key command on the server indicated by handle {{H}}. The
82hash value for {{KEY}} is obtained by the {{HASH}} procedure, which
83defaults to the one provided by the Chicken SRFI-69
84implementation. Returns {{#t}} on success, {{#f}} otherwise.
85
86
87==== Server handles
88
89All procedures in this library operate on a server handle object,
90which is created by the {{connect}} procedure. The following predicate
91and accessors are available for accessing a server handle:
92
93<procedure>(server-handle? H)</procedure>
94
95Returns {{#t}} is {{H}} is a Memcached server handle, {{#f}} otherwise.
96
97<procedure>(server-handle-host H)</procedure>
98
99Returns the host name of the given handle.
100
101<procedure>(server-handle-port H)</procedure>
102
103Returns the port number of the given handle.
104
105
106==== Convenience macro
107
108<macro>(with-server-connection H HOST PORT CMD ...)</macro>
109
110A convenience macro for creating and destroying a connection for a
111given set of commands. {{H}} is the name of the server handle that
112will be created. The connection is created before any of the forms
113{{CMD...}} are executed, and is destroyed after the last command is
114executed.
115
116=== Example
117
118 (with-server-connection h "localhost" 11211
119      (let ((foo 4))
120        (let ((success (set h "foo" foo)))
121         (let ((foo1 (get h "foo")))
122           (equal? foo foo1)))))
123
124=== Version History
125
126* 2.0 Using base64 for key hashes; removed dependency on s11n; added procedures gets, cas, append-to, prepend-to [thanks to Seth Alves]
127* 1.3 Detect if test script is run as root and attempt to start memcached as chicken user in that case
128* 1.2 Ensure that test script returns non-zero if the unit tests fail (thanks to mario)
129* 1.1 Importing chicken unit without get (thanks to felix)
130* 1.0 Initial release
131
132=== License
133
134Based on the
135[[http://github.com/olegkat/haskell-memcached|Haskell Memcached library]] by Evan Martin <martine@danga.com>.
136
137
138  Copyright 2011-2019 Ivan Raikov and Seth Alves.
139  All rights reserved.
140 
141  Redistribution and use in source and binary forms, with or without
142  modification, are permitted provided that the following conditions are
143  met:
144 
145  Redistributions of source code must retain the above copyright
146  notice, this list of conditions and the following disclaimer.
147 
148  Redistributions in binary form must reproduce the above copyright
149  notice, this list of conditions and the following disclaimer in the
150  documentation and/or other materials provided with the distribution.
151 
152  Neither the name of the author nor the names of its contributors may
153  be used to endorse or promote products derived from this software
154  without specific prior written permission.
155 
156  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
157  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
158  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
159  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
160  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
161  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
162  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
163  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
164  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
165  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
166  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
167  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.