/[de-setf-amqp]/README.md
ViewVC logotype

Contents of /README.md

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3 - (show annotations)
Tue Feb 23 09:05:39 2010 UTC (4 years, 2 months ago) by janderson
File size: 8791 byte(s)
Merge commit 'remotes/github/master' into remotes/git-svn
1
2
3 DE.SETF.AMQP: a Common Lisp client library for AMQP
4 -------
5
6 `de.setf.amqp` implements a native Common Lisp client library for the 'Advanced Message Queuing
7 Protocol' ([AMQP](http://en.wikipedia.org/wiki/AMQP)). The implementation comprises wire-level codecs, implementations
8 for the standard protocol objects and methods, a functional interface for message-,
9 stream- and object-based i/o, and a device-level simple-stream implementation.
10
11 The library targets the revisions of the published AMQP protocol as of versions
12 0.8, 0.9, and 0.10. This means that it should work with respective [RabbitMQ](http://www.rabbitmq.com/),
13 OpenAMQ, and [Qpid](http://qpid.apache.org/) implementations. The implementation architecture
14 should also accommodate a control structure appropriate for the prospective
15 1.0 version - as least as described in preliminary drafts.
16 For each version, a distinct package comprises the object and method
17 definitions for protocol entities and codecs as generated from the respective
18 specification documents.[[1]] Each collection is a
19 complete projection, which means there is some amount of duplication.
20 The names - classes, operators, fields, packages and directories all follow more-or-less the naming conventions of the
21 xml protocol documents[[2]]:
22
23 <table>
24 <tr><td>AMQP-1-1-0-8-0</td> <td>version 0.8</td> <td>[amqp0-8.xml, amqp0-8.pdf (2006-06)]</tr>
25 <tr><td>AMQP-1-1-0-9-0</td> <td>version 0.9</td> <td>[amqp0-9.xml, amqp0-9.pdf (2006-12)]</tr>
26 <tr><td>AMQP-1-1-0-9-1</td> <td>version 0.9r1</td> <td>[amqp0-9-1.xml, amqp0-9-1.pdf (2008-11-24)]</tr>
27 <tr><td>AMQP-1-1-0-10-0</td> <td>version 0.10</td> <td>[amqp.0-10.xml, amqp.0-10.pdf (2008-02-20)]</tr>
28 </table>
29
30 In order to modify the translation and/or generate new codecs consult the `:de.setf.amqp.tools` module.
31
32 All protocol versions are expressed through a common interface[[3]] which is specialized for the common
33 abstract classes. The initial connection phase determines the correct concrete connection implementation
34 to be used to communicate with the broker. Given which the other concrete object and method classes are
35 elected from the same package. One determines the version to be supported directly by loading the respective
36 version's `.asd` file, which makes its connection class available for negotiation.
37
38 [1]: tools/spec.lisp
39 [2]: http://www.amqp.org/confluence/display/AMQP/AMQP+Specification
40 [3]: documentation/index.html
41
42
43 Status
44 ------
45
46 This is intended as the base for a distributed semantic store.
47 What one has here is a reasonably complete engineering prototype.
48 It consumes phenomenal amounts of memory and runs astonishingly slowly:
49 5 - 10 milliseconds and 1 to 10 thousand bytes per round trip.
50 A request entails ten levels of generic function dispatch, half of which require keyword processing.
51 A response call stack is about as deep, but with somewhat less keyword processing.
52 As almost everything between the interface commands and the frame buffers is generated code, once it is clear
53 which aspects should remain available for specialization and/or optional arguments, the protocol call
54 stack would benefit from recasting uninteresting elements as ordinary functions of fixed arguments - depending
55 on implementation type, by a factor of ten to sixty.
56
57 It would also be nice to generate a table similar to [RabbitMQ's](http://www.rabbitmq.com/specification.html) to
58 record protocol conformance and compatibility with brokers. Eventually.
59 The present tests are limited to
60
61 - [codec](test/AMQP-1-1-0-9-1/test.lisp) unit tests which validate the respective version's codecs for default
62 argument values.
63 - in-memory loop-back [tests](test/test.lisp), used to ensure (for a recent version) that a round-trip
64 does not cons
65 - simple data exchanges with a broker.
66
67
68 The library has been built and [probed](file:///examples/examples.lisp) in the following combinations
69
70 <table>
71 <tr><td style='text-align: right;'>AMQP broker<br/>lisp implementation</td><th>RabbittMQ</th><th>QPID</th></tr>
72 <tr><th>MCL</th><td>MCL-5.2, RabbitMQ 1.7.1, AMQP-0.8r0</td><td>MCL-5.2, QPID-0.5, AMQP-0.9r1</td></tr>
73 <tr><th>CCL</th><td/><td>CCL-1.4, QPID-0.5, AMQP-0.9r1</td></tr>
74 <tr><th>SBCL</th><td/><td>SBCL-1.0.35, QPID-0.5, AMQP-0.9r1</td></tr>
75 </table>
76
77 For example,
78
79 $ sbcl
80 This is SBCL 1.0.35, an implementation of ANSI Common Lisp.
81 More information about SBCL is available at <http://www.sbcl.org/>.
82
83 * (in-package :amqp.i)
84
85 #<PACKAGE "DE.SETF.AMQP.IMPLEMENTATION">
86 * (defparameter *c* (make-instance 'amqp:connection :uri "amqp://guest:guest@localhost/"))
87
88 *C*
89 * (defparameter *ch1* (amqp:channel *c* :uri (uri "amqp:///")))
90
91 *CH1*
92 * (defparameter *ch1.basic* (amqp:basic *ch1*))
93
94 *CH1.BASIC*
95 * (defparameter *ch1.ex* (amqp:exchange *ch1* :exchange "ex" :type "direct"))
96
97 *CH1.EX*
98 * (defparameter *ch1.q* (amqp:queue *ch1* :queue "q1"))
99
100 *CH1.Q*
101 * (amqp:request-declare *ch1.q*)
102
103 #<AMQP-1-1-0-9-1:QUEUE {11D7A0F1}>
104 * (amqp:request-bind *ch1.q* :exchange *ch1.ex* :queue *ch1.q* :routing-key "/")
105
106 #<AMQP-1-1-0-9-1:QUEUE {11D7A0F1}>
107 * (defparameter *ch2* (amqp:channel *c* :uri (uri "amqp:///")))
108
109 *CH2*
110 * (defparameter *ch2.basic* (amqp:basic *ch2*))
111
112 *CH2.BASIC*
113 * (defparameter *ch2.q* (amqp:queue *ch2* :queue "q1"))
114
115 *CH2.Q*
116 * (amqp:request-declare *ch2.q*)
117
118 #<AMQP-1-1-0-9-1:QUEUE {11DA6891}>
119 * (list
120 (amqp:request-publish *ch1.basic* :exchange *ch1.ex*
121 :body (format nil "this is ~a" (gensym "test #"))
122 :routing-key "/")
123 (amqp:request-get *ch2.basic* :queue *ch2.q*))
124
125 ("this is test #1282" "this is test #1624")
126 * (amqp:request-get *ch2.basic* :queue *ch2.q*)
127
128 "this is test #1820"
129 * (amqp:request-get *ch2.basic* :queue *ch2.q*)
130
131 "this is test #1998"
132 * (amqp:request-get *ch2.basic* :queue *ch2.q*)
133
134 "this is test #2011"
135 * (amqp:request-get *ch2.basic* :queue *ch2.q*)
136
137 "this is test #2014"
138 * (amqp:request-get *ch2.basic* :queue *ch2.q*)
139
140 "this is test #2022"
141 * (amqp:request-get *ch2.basic* :queue *ch2.q*)
142
143 "this is test #2028"
144 * (amqp:request-get *ch2.basic* :queue *ch2.q*)
145
146 "this is test #2179"
147 * (amqp:request-get *ch2.basic* :queue *ch2.q*)
148
149 "this is test #1282"
150 * (amqp:request-get *ch2.basic* :queue *ch2.q*)
151
152 NIL
153 *
154
155 Which, as an aside, illustrates that brokered messages persist between connections until they have been consumed.
156 Of which a default QPID broker with no persistence support was observed to cache only about 500k bytes
157 (ca. 25,000 messages of 20 bytes each).
158
159
160 Downloading
161 -----------
162
163 A [.dmg](http://github.com/downloads/lisp/de.setf.amqp/amqp-20100214-0.3.dmg) is available for MCL-5.2.
164 Saved images are available for [ccl](http://github.com/downloads/lisp/de.setf.amqp/ccl-amqp.image.zip)
165 and [sbcl](http://github.com/downloads/lisp/de.setf.amqp/sbcl-amqp.core.zip).
166
167 Building
168 ---------
169
170 In principle, `de.setf.amqp` is built with [`asdf`](http://www.common-lisp.net/projects/asdf).
171 Once one has the sources and the `asdf` configuration in place, evaluate
172
173 (asdf:operate 'asdf:load-op :de.setf.amqp.amqp-1-1-0-8-0)
174 (asdf:operate 'asdf:load-op :de.setf.amqp.amqp-1-1-0-9-0)
175 (asdf:operate 'asdf:load-op :de.setf.amqp.amqp-1-1-0-9-1)
176
177 to load the respective version. The versions intend to be compatible and connections should
178 negotiate automatically to use the correct implementation.
179 Please consult the detailed instructions for the respective [runtime](./readmes/README-build.md) for more information.
180
181
182 Licensing
183 ---------
184
185 This version is released under version 3 of the GNU Affero license (GAL).[[5]]
186 The required components are included as per the respective licenses and covered,
187 in this combined form, under the GAL as well
188
189 - [alexandria](mailto:alexandria-devel@common-lisp.net) : Public Domain
190 - [usocket](mailto:usocket-devel@common-lisp.net) : MIT, through 2007. later work unspecified
191 - 2003 Erik Enge
192 - 2006-2007 Erik Huelsmann
193 - closer-mop : MIT-style
194 - 2005 - 2010 [Pascal Costanza](http://p-cos.net)
195 - [bordeaux-threads](mailto:bordeaux-threads-devel@common-lisp.net) : MIT-style, with additional attributions undated.[[6]]
196 - -2006 Greg Pfeil
197 - cl-ppcre : equivalent to MIT
198 - 2002-2008, [Dr. Edmund Weitz](http://www.weitz.de)
199 - com.b9.puri : LLGPL, by which com.b9.puri.ppcre is also covered by the LLGPL
200 - 1999-2001 [Franz, Inc](mailto:opensource@franz.com).
201 - 2003 [Kevin Rosenberg](mailto:kevin@rosenberg.net)
202
203
204 [5]: agpl.txt
205 [6]: http://common-lisp.net/project/bordeaux-threads/darcs/bordeaux-threads/CONTRIBUTORS
206
207 --------
208 ![made with mcl](http://www.digitool.com/img/mcl-made-1.gif "Made With MCL")
209
210

  ViewVC Help
Powered by ViewVC 1.1.5