desperados 0.1

Sign up to get free protection for your applications and to get access to all the features.
data/LICENSE ADDED
@@ -0,0 +1,481 @@
1
+ GNU LIBRARY GENERAL PUBLIC LICENSE
2
+ Version 2, June 1991
3
+
4
+ Copyright (C) 1991 Free Software Foundation, Inc.
5
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
6
+ Everyone is permitted to copy and distribute verbatim copies
7
+ of this license document, but changing it is not allowed.
8
+
9
+ [This is the first released version of the library GPL. It is
10
+ numbered 2 because it goes with version 2 of the ordinary GPL.]
11
+
12
+ Preamble
13
+
14
+ The licenses for most software are designed to take away your
15
+ freedom to share and change it. By contrast, the GNU General Public
16
+ Licenses are intended to guarantee your freedom to share and change
17
+ free software--to make sure the software is free for all its users.
18
+
19
+ This license, the Library General Public License, applies to some
20
+ specially designated Free Software Foundation software, and to any
21
+ other libraries whose authors decide to use it. You can use it for
22
+ your libraries, too.
23
+
24
+ When we speak of free software, we are referring to freedom, not
25
+ price. Our General Public Licenses are designed to make sure that you
26
+ have the freedom to distribute copies of free software (and charge for
27
+ this service if you wish), that you receive source code or can get it
28
+ if you want it, that you can change the software or use pieces of it
29
+ in new free programs; and that you know you can do these things.
30
+
31
+ To protect your rights, we need to make restrictions that forbid
32
+ anyone to deny you these rights or to ask you to surrender the rights.
33
+ These restrictions translate to certain responsibilities for you if
34
+ you distribute copies of the library, or if you modify it.
35
+
36
+ For example, if you distribute copies of the library, whether gratis
37
+ or for a fee, you must give the recipients all the rights that we gave
38
+ you. You must make sure that they, too, receive or can get the source
39
+ code. If you link a program with the library, you must provide
40
+ complete object files to the recipients so that they can relink them
41
+ with the library, after making changes to the library and recompiling
42
+ it. And you must show them these terms so they know their rights.
43
+
44
+ Our method of protecting your rights has two steps: (1) copyright
45
+ the library, and (2) offer you this license which gives you legal
46
+ permission to copy, distribute and/or modify the library.
47
+
48
+ Also, for each distributor's protection, we want to make certain
49
+ that everyone understands that there is no warranty for this free
50
+ library. If the library is modified by someone else and passed on, we
51
+ want its recipients to know that what they have is not the original
52
+ version, so that any problems introduced by others will not reflect on
53
+ the original authors' reputations.
54
+
55
+ Finally, any free program is threatened constantly by software
56
+ patents. We wish to avoid the danger that companies distributing free
57
+ software will individually obtain patent licenses, thus in effect
58
+ transforming the program into proprietary software. To prevent this,
59
+ we have made it clear that any patent must be licensed for everyone's
60
+ free use or not licensed at all.
61
+
62
+ Most GNU software, including some libraries, is covered by the ordinary
63
+ GNU General Public License, which was designed for utility programs. This
64
+ license, the GNU Library General Public License, applies to certain
65
+ designated libraries. This license is quite different from the ordinary
66
+ one; be sure to read it in full, and don't assume that anything in it is
67
+ the same as in the ordinary license.
68
+
69
+ The reason we have a separate public license for some libraries is that
70
+ they blur the distinction we usually make between modifying or adding to a
71
+ program and simply using it. Linking a program with a library, without
72
+ changing the library, is in some sense simply using the library, and is
73
+ analogous to running a utility program or application program. However, in
74
+ a textual and legal sense, the linked executable is a combined work, a
75
+ derivative of the original library, and the ordinary General Public License
76
+ treats it as such.
77
+
78
+ Because of this blurred distinction, using the ordinary General
79
+ Public License for libraries did not effectively promote software
80
+ sharing, because most developers did not use the libraries. We
81
+ concluded that weaker conditions might promote sharing better.
82
+
83
+ However, unrestricted linking of non-free programs would deprive the
84
+ users of those programs of all benefit from the free status of the
85
+ libraries themselves. This Library General Public License is intended to
86
+ permit developers of non-free programs to use free libraries, while
87
+ preserving your freedom as a user of such programs to change the free
88
+ libraries that are incorporated in them. (We have not seen how to achieve
89
+ this as regards changes in header files, but we have achieved it as regards
90
+ changes in the actual functions of the Library.) The hope is that this
91
+ will lead to faster development of free libraries.
92
+
93
+ The precise terms and conditions for copying, distribution and
94
+ modification follow. Pay close attention to the difference between a
95
+ "work based on the library" and a "work that uses the library". The
96
+ former contains code derived from the library, while the latter only
97
+ works together with the library.
98
+
99
+ Note that it is possible for a library to be covered by the ordinary
100
+ General Public License rather than by this special one.
101
+
102
+ GNU LIBRARY GENERAL PUBLIC LICENSE
103
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
104
+
105
+ 0. This License Agreement applies to any software library which
106
+ contains a notice placed by the copyright holder or other authorized
107
+ party saying it may be distributed under the terms of this Library
108
+ General Public License (also called "this License"). Each licensee is
109
+ addressed as "you".
110
+
111
+ A "library" means a collection of software functions and/or data
112
+ prepared so as to be conveniently linked with application programs
113
+ (which use some of those functions and data) to form executables.
114
+
115
+ The "Library", below, refers to any such software library or work
116
+ which has been distributed under these terms. A "work based on the
117
+ Library" means either the Library or any derivative work under
118
+ copyright law: that is to say, a work containing the Library or a
119
+ portion of it, either verbatim or with modifications and/or translated
120
+ straightforwardly into another language. (Hereinafter, translation is
121
+ included without limitation in the term "modification".)
122
+
123
+ "Source code" for a work means the preferred form of the work for
124
+ making modifications to it. For a library, complete source code means
125
+ all the source code for all modules it contains, plus any associated
126
+ interface definition files, plus the scripts used to control compilation
127
+ and installation of the library.
128
+
129
+ Activities other than copying, distribution and modification are not
130
+ covered by this License; they are outside its scope. The act of
131
+ running a program using the Library is not restricted, and output from
132
+ such a program is covered only if its contents constitute a work based
133
+ on the Library (independent of the use of the Library in a tool for
134
+ writing it). Whether that is true depends on what the Library does
135
+ and what the program that uses the Library does.
136
+
137
+ 1. You may copy and distribute verbatim copies of the Library's
138
+ complete source code as you receive it, in any medium, provided that
139
+ you conspicuously and appropriately publish on each copy an
140
+ appropriate copyright notice and disclaimer of warranty; keep intact
141
+ all the notices that refer to this License and to the absence of any
142
+ warranty; and distribute a copy of this License along with the
143
+ Library.
144
+
145
+ You may charge a fee for the physical act of transferring a copy,
146
+ and you may at your option offer warranty protection in exchange for a
147
+ fee.
148
+
149
+ 2. You may modify your copy or copies of the Library or any portion
150
+ of it, thus forming a work based on the Library, and copy and
151
+ distribute such modifications or work under the terms of Section 1
152
+ above, provided that you also meet all of these conditions:
153
+
154
+ a) The modified work must itself be a software library.
155
+
156
+ b) You must cause the files modified to carry prominent notices
157
+ stating that you changed the files and the date of any change.
158
+
159
+ c) You must cause the whole of the work to be licensed at no
160
+ charge to all third parties under the terms of this License.
161
+
162
+ d) If a facility in the modified Library refers to a function or a
163
+ table of data to be supplied by an application program that uses
164
+ the facility, other than as an argument passed when the facility
165
+ is invoked, then you must make a good faith effort to ensure that,
166
+ in the event an application does not supply such function or
167
+ table, the facility still operates, and performs whatever part of
168
+ its purpose remains meaningful.
169
+
170
+ (For example, a function in a library to compute square roots has
171
+ a purpose that is entirely well-defined independent of the
172
+ application. Therefore, Subsection 2d requires that any
173
+ application-supplied function or table used by this function must
174
+ be optional: if the application does not supply it, the square
175
+ root function must still compute square roots.)
176
+
177
+ These requirements apply to the modified work as a whole. If
178
+ identifiable sections of that work are not derived from the Library,
179
+ and can be reasonably considered independent and separate works in
180
+ themselves, then this License, and its terms, do not apply to those
181
+ sections when you distribute them as separate works. But when you
182
+ distribute the same sections as part of a whole which is a work based
183
+ on the Library, the distribution of the whole must be on the terms of
184
+ this License, whose permissions for other licensees extend to the
185
+ entire whole, and thus to each and every part regardless of who wrote
186
+ it.
187
+
188
+ Thus, it is not the intent of this section to claim rights or contest
189
+ your rights to work written entirely by you; rather, the intent is to
190
+ exercise the right to control the distribution of derivative or
191
+ collective works based on the Library.
192
+
193
+ In addition, mere aggregation of another work not based on the Library
194
+ with the Library (or with a work based on the Library) on a volume of
195
+ a storage or distribution medium does not bring the other work under
196
+ the scope of this License.
197
+
198
+ 3. You may opt to apply the terms of the ordinary GNU General Public
199
+ License instead of this License to a given copy of the Library. To do
200
+ this, you must alter all the notices that refer to this License, so
201
+ that they refer to the ordinary GNU General Public License, version 2,
202
+ instead of to this License. (If a newer version than version 2 of the
203
+ ordinary GNU General Public License has appeared, then you can specify
204
+ that version instead if you wish.) Do not make any other change in
205
+ these notices.
206
+
207
+ Once this change is made in a given copy, it is irreversible for
208
+ that copy, so the ordinary GNU General Public License applies to all
209
+ subsequent copies and derivative works made from that copy.
210
+
211
+ This option is useful when you wish to copy part of the code of
212
+ the Library into a program that is not a library.
213
+
214
+ 4. You may copy and distribute the Library (or a portion or
215
+ derivative of it, under Section 2) in object code or executable form
216
+ under the terms of Sections 1 and 2 above provided that you accompany
217
+ it with the complete corresponding machine-readable source code, which
218
+ must be distributed under the terms of Sections 1 and 2 above on a
219
+ medium customarily used for software interchange.
220
+
221
+ If distribution of object code is made by offering access to copy
222
+ from a designated place, then offering equivalent access to copy the
223
+ source code from the same place satisfies the requirement to
224
+ distribute the source code, even though third parties are not
225
+ compelled to copy the source along with the object code.
226
+
227
+ 5. A program that contains no derivative of any portion of the
228
+ Library, but is designed to work with the Library by being compiled or
229
+ linked with it, is called a "work that uses the Library". Such a
230
+ work, in isolation, is not a derivative work of the Library, and
231
+ therefore falls outside the scope of this License.
232
+
233
+ However, linking a "work that uses the Library" with the Library
234
+ creates an executable that is a derivative of the Library (because it
235
+ contains portions of the Library), rather than a "work that uses the
236
+ library". The executable is therefore covered by this License.
237
+ Section 6 states terms for distribution of such executables.
238
+
239
+ When a "work that uses the Library" uses material from a header file
240
+ that is part of the Library, the object code for the work may be a
241
+ derivative work of the Library even though the source code is not.
242
+ Whether this is true is especially significant if the work can be
243
+ linked without the Library, or if the work is itself a library. The
244
+ threshold for this to be true is not precisely defined by law.
245
+
246
+ If such an object file uses only numerical parameters, data
247
+ structure layouts and accessors, and small macros and small inline
248
+ functions (ten lines or less in length), then the use of the object
249
+ file is unrestricted, regardless of whether it is legally a derivative
250
+ work. (Executables containing this object code plus portions of the
251
+ Library will still fall under Section 6.)
252
+
253
+ Otherwise, if the work is a derivative of the Library, you may
254
+ distribute the object code for the work under the terms of Section 6.
255
+ Any executables containing that work also fall under Section 6,
256
+ whether or not they are linked directly with the Library itself.
257
+
258
+ 6. As an exception to the Sections above, you may also compile or
259
+ link a "work that uses the Library" with the Library to produce a
260
+ work containing portions of the Library, and distribute that work
261
+ under terms of your choice, provided that the terms permit
262
+ modification of the work for the customer's own use and reverse
263
+ engineering for debugging such modifications.
264
+
265
+ You must give prominent notice with each copy of the work that the
266
+ Library is used in it and that the Library and its use are covered by
267
+ this License. You must supply a copy of this License. If the work
268
+ during execution displays copyright notices, you must include the
269
+ copyright notice for the Library among them, as well as a reference
270
+ directing the user to the copy of this License. Also, you must do one
271
+ of these things:
272
+
273
+ a) Accompany the work with the complete corresponding
274
+ machine-readable source code for the Library including whatever
275
+ changes were used in the work (which must be distributed under
276
+ Sections 1 and 2 above); and, if the work is an executable linked
277
+ with the Library, with the complete machine-readable "work that
278
+ uses the Library", as object code and/or source code, so that the
279
+ user can modify the Library and then relink to produce a modified
280
+ executable containing the modified Library. (It is understood
281
+ that the user who changes the contents of definitions files in the
282
+ Library will not necessarily be able to recompile the application
283
+ to use the modified definitions.)
284
+
285
+ b) Accompany the work with a written offer, valid for at
286
+ least three years, to give the same user the materials
287
+ specified in Subsection 6a, above, for a charge no more
288
+ than the cost of performing this distribution.
289
+
290
+ c) If distribution of the work is made by offering access to copy
291
+ from a designated place, offer equivalent access to copy the above
292
+ specified materials from the same place.
293
+
294
+ d) Verify that the user has already received a copy of these
295
+ materials or that you have already sent this user a copy.
296
+
297
+ For an executable, the required form of the "work that uses the
298
+ Library" must include any data and utility programs needed for
299
+ reproducing the executable from it. However, as a special exception,
300
+ the source code distributed need not include anything that is normally
301
+ distributed (in either source or binary form) with the major
302
+ components (compiler, kernel, and so on) of the operating system on
303
+ which the executable runs, unless that component itself accompanies
304
+ the executable.
305
+
306
+ It may happen that this requirement contradicts the license
307
+ restrictions of other proprietary libraries that do not normally
308
+ accompany the operating system. Such a contradiction means you cannot
309
+ use both them and the Library together in an executable that you
310
+ distribute.
311
+
312
+ 7. You may place library facilities that are a work based on the
313
+ Library side-by-side in a single library together with other library
314
+ facilities not covered by this License, and distribute such a combined
315
+ library, provided that the separate distribution of the work based on
316
+ the Library and of the other library facilities is otherwise
317
+ permitted, and provided that you do these two things:
318
+
319
+ a) Accompany the combined library with a copy of the same work
320
+ based on the Library, uncombined with any other library
321
+ facilities. This must be distributed under the terms of the
322
+ Sections above.
323
+
324
+ b) Give prominent notice with the combined library of the fact
325
+ that part of it is a work based on the Library, and explaining
326
+ where to find the accompanying uncombined form of the same work.
327
+
328
+ 8. You may not copy, modify, sublicense, link with, or distribute
329
+ the Library except as expressly provided under this License. Any
330
+ attempt otherwise to copy, modify, sublicense, link with, or
331
+ distribute the Library is void, and will automatically terminate your
332
+ rights under this License. However, parties who have received copies,
333
+ or rights, from you under this License will not have their licenses
334
+ terminated so long as such parties remain in full compliance.
335
+
336
+ 9. You are not required to accept this License, since you have not
337
+ signed it. However, nothing else grants you permission to modify or
338
+ distribute the Library or its derivative works. These actions are
339
+ prohibited by law if you do not accept this License. Therefore, by
340
+ modifying or distributing the Library (or any work based on the
341
+ Library), you indicate your acceptance of this License to do so, and
342
+ all its terms and conditions for copying, distributing or modifying
343
+ the Library or works based on it.
344
+
345
+ 10. Each time you redistribute the Library (or any work based on the
346
+ Library), the recipient automatically receives a license from the
347
+ original licensor to copy, distribute, link with or modify the Library
348
+ subject to these terms and conditions. You may not impose any further
349
+ restrictions on the recipients' exercise of the rights granted herein.
350
+ You are not responsible for enforcing compliance by third parties to
351
+ this License.
352
+
353
+ 11. If, as a consequence of a court judgment or allegation of patent
354
+ infringement or for any other reason (not limited to patent issues),
355
+ conditions are imposed on you (whether by court order, agreement or
356
+ otherwise) that contradict the conditions of this License, they do not
357
+ excuse you from the conditions of this License. If you cannot
358
+ distribute so as to satisfy simultaneously your obligations under this
359
+ License and any other pertinent obligations, then as a consequence you
360
+ may not distribute the Library at all. For example, if a patent
361
+ license would not permit royalty-free redistribution of the Library by
362
+ all those who receive copies directly or indirectly through you, then
363
+ the only way you could satisfy both it and this License would be to
364
+ refrain entirely from distribution of the Library.
365
+
366
+ If any portion of this section is held invalid or unenforceable under any
367
+ particular circumstance, the balance of the section is intended to apply,
368
+ and the section as a whole is intended to apply in other circumstances.
369
+
370
+ It is not the purpose of this section to induce you to infringe any
371
+ patents or other property right claims or to contest validity of any
372
+ such claims; this section has the sole purpose of protecting the
373
+ integrity of the free software distribution system which is
374
+ implemented by public license practices. Many people have made
375
+ generous contributions to the wide range of software distributed
376
+ through that system in reliance on consistent application of that
377
+ system; it is up to the author/donor to decide if he or she is willing
378
+ to distribute software through any other system and a licensee cannot
379
+ impose that choice.
380
+
381
+ This section is intended to make thoroughly clear what is believed to
382
+ be a consequence of the rest of this License.
383
+
384
+ 12. If the distribution and/or use of the Library is restricted in
385
+ certain countries either by patents or by copyrighted interfaces, the
386
+ original copyright holder who places the Library under this License may add
387
+ an explicit geographical distribution limitation excluding those countries,
388
+ so that distribution is permitted only in or among countries not thus
389
+ excluded. In such case, this License incorporates the limitation as if
390
+ written in the body of this License.
391
+
392
+ 13. The Free Software Foundation may publish revised and/or new
393
+ versions of the Library General Public License from time to time.
394
+ Such new versions will be similar in spirit to the present version,
395
+ but may differ in detail to address new problems or concerns.
396
+
397
+ Each version is given a distinguishing version number. If the Library
398
+ specifies a version number of this License which applies to it and
399
+ "any later version", you have the option of following the terms and
400
+ conditions either of that version or of any later version published by
401
+ the Free Software Foundation. If the Library does not specify a
402
+ license version number, you may choose any version ever published by
403
+ the Free Software Foundation.
404
+
405
+ 14. If you wish to incorporate parts of the Library into other free
406
+ programs whose distribution conditions are incompatible with these,
407
+ write to the author to ask for permission. For software which is
408
+ copyrighted by the Free Software Foundation, write to the Free
409
+ Software Foundation; we sometimes make exceptions for this. Our
410
+ decision will be guided by the two goals of preserving the free status
411
+ of all derivatives of our free software and of promoting the sharing
412
+ and reuse of software generally.
413
+
414
+ NO WARRANTY
415
+
416
+ 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
417
+ WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
418
+ EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
419
+ OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
420
+ KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
421
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
422
+ PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
423
+ LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
424
+ THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
425
+
426
+ 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
427
+ WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
428
+ AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
429
+ FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
430
+ CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
431
+ LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
432
+ RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
433
+ FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
434
+ SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
435
+ DAMAGES.
436
+
437
+ END OF TERMS AND CONDITIONS
438
+
439
+ How to Apply These Terms to Your New Libraries
440
+
441
+ If you develop a new library, and you want it to be of the greatest
442
+ possible use to the public, we recommend making it free software that
443
+ everyone can redistribute and change. You can do so by permitting
444
+ redistribution under these terms (or, alternatively, under the terms of the
445
+ ordinary General Public License).
446
+
447
+ To apply these terms, attach the following notices to the library. It is
448
+ safest to attach them to the start of each source file to most effectively
449
+ convey the exclusion of warranty; and each file should have at least the
450
+ "copyright" line and a pointer to where the full notice is found.
451
+
452
+ <one line to give the library's name and a brief idea of what it does.>
453
+ Copyright (C) <year> <name of author>
454
+
455
+ This library is free software; you can redistribute it and/or
456
+ modify it under the terms of the GNU Library General Public
457
+ License as published by the Free Software Foundation; either
458
+ version 2 of the License, or (at your option) any later version.
459
+
460
+ This library is distributed in the hope that it will be useful,
461
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
462
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
463
+ Library General Public License for more details.
464
+
465
+ You should have received a copy of the GNU Library General Public
466
+ License along with this library; if not, write to the Free Software
467
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
468
+
469
+ Also add information on how to contact you by electronic and paper mail.
470
+
471
+ You should also get your employer (if you work as a programmer) or your
472
+ school, if any, to sign a "copyright disclaimer" for the library, if
473
+ necessary. Here is a sample; alter the names:
474
+
475
+ Yoyodyne, Inc., hereby disclaims all copyright interest in the
476
+ library `Frob' (a library for tweaking knobs) written by James Random Hacker.
477
+
478
+ <signature of Ty Coon>, 1 April 1990
479
+ Ty Coon, President of Vice
480
+
481
+ That's all there is to it!
@@ -0,0 +1,45 @@
1
+ = desperados: A Ruby library for Ceph's Rados
2
+
3
+ Ceph is a distributed network storage and file system. It's based on a
4
+ reliable and scalable distributed object store calles RADOS. More
5
+ about it here: http://ceph.newdream.net
6
+
7
+ Desperados is a Ruby wrapper for the C++ librados library, making
8
+ interacting with a Ceph cluster in Ruby very easy.
9
+
10
+ == Basic Example
11
+
12
+ require 'rados'
13
+ Rados::initialize
14
+
15
+ pool = Rados::Pool.create("mypool")
16
+ pool.write("mykey", "somedata")
17
+ pool.read("mykey") == "somedata"
18
+
19
+ == Object Orientated Example
20
+
21
+ require 'rados'
22
+ Rados::initialize
23
+
24
+ pool = Rados::Pool.create("mypool")
25
+ o = pool.objects.new("mykey")
26
+ o.write("Once upon")
27
+ o.write(" a time")
28
+ o.seek(0)
29
+ o.read == "Once upon a time"
30
+ o = pool.objects.find("mykey")
31
+ o.seek(5)
32
+ o.read == "upon a time"
33
+
34
+ == Configuration
35
+
36
+ librados will read your ceph.conf config file to discover your
37
+ cluster's monitors, so that needs to be available (usually in
38
+ ./ceph.conf or /etc/ceph/ceph.conf)
39
+
40
+ == About
41
+
42
+ Author:: John Leach (mailto:john@johnleach.co.uk)
43
+ Copyright:: Copyright (c) 2010, 2011 John Leach
44
+ License:: LGPL
45
+ Github:: http://github.com/johnl/desperados/tree/master
@@ -0,0 +1,9 @@
1
+ require 'rake'
2
+ require 'rubygems'
3
+ require 'rspec/core/rake_task.rb'
4
+ require 'bundler'
5
+ Bundler::GemHelper.install_tasks
6
+
7
+
8
+ desc "Run all specs"
9
+ RSpec::Core::RakeTask.new('spec')
@@ -0,0 +1,19 @@
1
+ # -*- encoding: utf-8 -*-
2
+
3
+ Gem::Specification.new do |s|
4
+ s.name = "desperados"
5
+ s.version = "0.1"
6
+ s.platform = Gem::Platform::RUBY
7
+ s.authors = ["John Leach"]
8
+ s.email = ["john@johnleach.co.uk.co.uk"]
9
+ s.homepage = "https://github.com/johnl/desperados"
10
+ s.summary = %q{Ruby library for interacting with Ceph's RADOS}
11
+ s.description = %q{Ruby library for Ceph's Reliable Autonomic Distributed Object Store. Wraps the C++ librados library with Ruby love. }
12
+
13
+ s.files = `git ls-files`.split("\n")
14
+ s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
15
+ s.require_paths = ["lib"]
16
+
17
+ s.add_dependency 'ffi', "~> 1.0.0"
18
+
19
+ end
@@ -0,0 +1,40 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ require File.dirname(__FILE__) + '/../lib/rados'
4
+ require 'logger'
5
+ require 'benchmark'
6
+
7
+ log = Logger.new STDERR
8
+ include Rados
9
+
10
+ Rados::initialize
11
+
12
+ max_objects = 10000
13
+
14
+ obj_size = 8192
15
+
16
+ loop do
17
+ pool_name = "rados-load-#{rand(0xffffff).to_s(36)}"
18
+ log.info "Creating pool #{pool_name}"
19
+ pool = Pool.create pool_name
20
+ log.info "Writing #{max_objects} objects"
21
+ bm = Benchmark.measure do
22
+ max_objects.times do |i|
23
+ pool.write i.to_s, (i * obj_size).to_s # FIXME: shouldn't have to to_s
24
+ end
25
+ end
26
+ log.info "%.2f objects/second" % (max_objects / bm.real)
27
+ log.info "Reading back #{max_objects} random objects"
28
+ bm = Benchmark::measure do
29
+ max_objects.times do
30
+ i = rand(max_objects)
31
+ data = pool.read i.to_s
32
+ if data != (i * obj_size).to_s
33
+ logger.warn "data in oid #{i} in pool #{pool.name} did not match written"
34
+ end
35
+ end
36
+ end
37
+ log.info "%.2f objects/second" % (max_objects / bm.real)
38
+ log.info "Destroying pool #{pool.name}"
39
+ pool.destroy
40
+ end
@@ -0,0 +1,224 @@
1
+ require 'ffi'
2
+
3
+ module Rados #:nodoc:
4
+ module Lib #:nodoc:
5
+ extend FFI::Library
6
+
7
+ ffi_lib 'rados'
8
+
9
+ attach_function 'rados_initialize', [ :int, :varargs ], :int
10
+ attach_function 'rados_deinitialize', [], :void
11
+ attach_function 'rados_open_pool', [:string, :pointer], :int
12
+ attach_function 'rados_create_pool', [:string], :int
13
+ attach_function 'rados_write', [:pointer, :string, :off_t, :buffer_in, :size_t], :int
14
+ attach_function 'rados_read', [:pointer, :string, :off_t, :pointer, :size_t], :int
15
+ attach_function 'rados_remove', [:pointer, :string], :int
16
+ attach_function 'rados_delete_pool', [:pointer], :int
17
+ end
18
+
19
+ class RadosError < StandardError ; end
20
+ class PoolNotFound < RadosError ; end
21
+ class WriteError < RadosError ; end
22
+ class ShortWriteError < WriteError ; end
23
+ class ReadError < RadosError ; end
24
+ class ObjectNotFound < ReadError ; end
25
+
26
+ # Initialize the Rados library. Must be called once before any other
27
+ # operations.
28
+ def self.initialize
29
+ unless @initialized
30
+ ret = Lib.rados_initialize(0)
31
+ if ret < 0 # Blocked by ceph bug #512
32
+ raise RadosError, "Could not initialize rados: #{ret}"
33
+ end
34
+ @initialized = true
35
+ end
36
+ @initialized
37
+ end
38
+
39
+ # A Rados::Object represents an object in a pool in a cluster.
40
+ class Object
41
+ attr_reader :id, :position, :pool
42
+
43
+ def initialize(attributes = {})
44
+ @id = attributes[:id]
45
+ @pool = attributes[:pool]
46
+ @position = 0
47
+ end
48
+
49
+ def write(buf)
50
+ # FIXME: If the following does a part write and raises an
51
+ # exception then the @position is invalid
52
+ @position += pool.write(id, buf, :offset => @position)
53
+ self
54
+ end
55
+
56
+ def read
57
+ # FIXME: If the following does a part read and raises an
58
+ # exception then the @position is invalid
59
+ buf = pool.read(id, :offset => @position)
60
+ if buf.size == 0
61
+ nil
62
+ else
63
+ @position += buf.size
64
+ buf
65
+ end
66
+ end
67
+
68
+ def seek(amount, whence = IO::SEEK_SET)
69
+ case whence
70
+ when IO::SEEK_SET
71
+ @position = amount
72
+ when IO::SEEK_CUR
73
+ @position += amount
74
+ end
75
+ end
76
+
77
+ end
78
+
79
+ class ObjectCollection
80
+
81
+ attr_reader :pool
82
+
83
+ def initialize(pool)
84
+ @pool = pool
85
+ end
86
+
87
+ def find(oid)
88
+ Object.new(:id => oid, :pool => pool)
89
+ end
90
+
91
+ def new(oid = nil)
92
+ Object.new(:id => oid, :pool => pool)
93
+ end
94
+
95
+ end
96
+
97
+ # Represents a Pool in the cluster. Use Pool.find to get a pool from the
98
+ # cluster and Pool.create to create new ones.
99
+ class Pool
100
+
101
+ # The name of this pool
102
+ attr_reader :name
103
+ # The objects in this pool. See Rados::ObjectCollection.
104
+ attr_reader :objects
105
+
106
+ def initialize(name) #:nodoc:
107
+ @name = name
108
+ @objects = ObjectCollection.new(self)
109
+ end
110
+
111
+ # Get the named pool from the cluster. Returns a Pool
112
+ # instance. Raises Rados::PoolNotFound if Pool doesn't exist
113
+ def self.find(name)
114
+ p = new(name)
115
+ p.pool
116
+ p
117
+ end
118
+
119
+ # Create a new pool in the cluster with the given name. Returns a
120
+ # Pool instance. Raises a RadosError exception if the pool could
121
+ # not be created.
122
+ def self.create(name)
123
+ ret = Lib.rados_create_pool(name)
124
+ if ret < 0
125
+ raise RadosError, "creating pool #{name}"
126
+ else
127
+ new(name)
128
+ end
129
+ end
130
+
131
+ # The internal Rados pool data stucture
132
+ def pool #:nodoc:
133
+ return @pool unless @pool.nil?
134
+ @pool_pointer = FFI::MemoryPointer.new :pointer
135
+ ret = Lib.rados_open_pool name, @pool_pointer
136
+ if ret < 0
137
+ raise PoolNotFound, name
138
+ end
139
+ @pool = @pool_pointer.get_pointer(0)
140
+ end
141
+
142
+ # Destroy the pool. Raises a RadosError exception if the pool
143
+ # could not be deleted.
144
+ def destroy
145
+ sanity_check "destroy already"
146
+ ret = Lib.rados_delete_pool(pool)
147
+ if ret < 0
148
+ raise RadosError, "deleting pool #{name}"
149
+ else
150
+ @destroyed = true
151
+ self
152
+ end
153
+ end
154
+
155
+ # Returns true if the pool as been marked as destroyed since
156
+ # instantiated.
157
+ def destroyed?
158
+ @destroyed == true
159
+ end
160
+
161
+ # Write the data <tt>buf</tt> to the object id <tt>oid</tt> in the
162
+ # pool. Both <tt>oid</tt> and <tt>buf</tt> should be
163
+ # strings. Returns the number of bytes written. If the write
164
+ # fails then a Rados::WriteError exception is raised. If the data
165
+ # was only partly written then a Rados::ShortWriteError exception
166
+ # is raised.
167
+ #
168
+ # Available options are:
169
+ # * <tt>:size</tt> - Number of bytes to write. Defaults to the size of <tt>buf</tt>
170
+ # * <tt>:offset</tt> - The number of bytes from the beginning of the object to start writing at. Defaults to 0.
171
+ def write(oid, buf, options = {})
172
+ sanity_check "write to"
173
+ offset = options.fetch(:offset, 0)
174
+ len = options.fetch(:size, buf.size)
175
+ ret = Lib.rados_write(pool, oid, offset, buf, len)
176
+ if ret < 0
177
+ raise WriteError, "writing #{len} bytes at offset #{offset} to #{oid} in pool #{name}: #{ret}"
178
+ elsif ret < len
179
+ raise ShortWriteError, "writing #{len} bytes to pool #{name} only wrote #{ret}"
180
+ end
181
+ ret
182
+ end
183
+
184
+ # Reads data from the object id <tt>oid</tt> in the pool. Returns
185
+ # the data as a string. If no object with the oid exists, a
186
+ # Rados::ObjectNotFound exception is raised. If the read fails
187
+ # then a Rados::ReadError exception is raised.
188
+ #
189
+ # Available options are:
190
+ # * <tt>:size</tt> - The amount of data to read. As objects can be huge, it is unlikely that you'll want to load the entire thing into ram, so defaults to 8192 bytes.
191
+ # * <tt>:offset</tt> - The number of bytes from the beginning of the object to start writing at. Defaults to 0.
192
+ def read(oid, options = {})
193
+ sanity_check "read from"
194
+ offset = options.fetch(:offset, 0)
195
+ len = options.fetch(:size, 8192)
196
+ buf = FFI::MemoryPointer.new :char, len
197
+ ret = Lib.rados_read(pool, oid, offset, buf, len)
198
+ if ret == -2
199
+ raise ObjectNotFound, "reading from '#{oid}' in pool #{name}"
200
+ elsif ret < 0
201
+ raise ReadError, "reading #{len} bytes at offset #{offset} from #{oid} in pool #{name}: #{ret}"
202
+ end
203
+ buf.read_string(ret)
204
+ end
205
+
206
+ # Deletes the object id <tt>oid</tt> from the pool. If the object
207
+ # could not be removed then a Rados::RemoveError exception is
208
+ # raised.
209
+ def remove(oid)
210
+ sanity_check "remove from"
211
+ ret = Lib.rados_remove(pool, oid)
212
+ if ret < 0
213
+ raise RemoveError, "removing #{oid} from pool #{name}"
214
+ end
215
+ true
216
+ end
217
+
218
+ private
219
+
220
+ def sanity_check(action)
221
+ raise RadosError, "attempt to #{action} destroyed pool #{name}" if destroyed?
222
+ end
223
+ end
224
+ end
@@ -0,0 +1,34 @@
1
+ require File.join(File.dirname(__FILE__), '../lib/rados')
2
+ include Rados
3
+
4
+ describe ObjectCollection do
5
+ def a_pool
6
+ mock("pool")
7
+ end
8
+
9
+ it "should take pool as an option" do
10
+ pool = a_pool
11
+ oc = Rados::ObjectCollection.new(pool)
12
+ oc.pool.should == pool
13
+ end
14
+
15
+ describe "new" do
16
+ it "should return an new Rados::Object with the given id and pool" do
17
+ pool = a_pool
18
+ oc = Rados::ObjectCollection.new(pool)
19
+ o = oc.new("myobj")
20
+ o.pool.should == pool
21
+ o.id.should == "myobj"
22
+ end
23
+ end
24
+
25
+ describe "find" do
26
+ it "should return a new Rados::Object with the given id and pool" do
27
+ pool = a_pool
28
+ oc = Rados::ObjectCollection.new(pool)
29
+ o = oc.find("myobj")
30
+ o.pool.should == pool
31
+ o.id.should == "myobj"
32
+ end
33
+ end
34
+ end
@@ -0,0 +1,53 @@
1
+ require File.join(File.dirname(__FILE__), '../lib/rados')
2
+ include Rados
3
+
4
+ describe Object do
5
+ def a_pool
6
+ mock("pool")
7
+ end
8
+
9
+ it "should take id and pool options" do
10
+ pool = a_pool
11
+ o = Rados::Object.new(:id => "myobj", :pool => pool)
12
+ o.id.should == "myobj"
13
+ o.pool.should == pool
14
+ end
15
+
16
+ it "should write to the pool and increase the position" do
17
+ pool = a_pool
18
+ pool.should_receive(:write).with("myobj", "data", :offset => 0).and_return(4)
19
+ o = Rados::Object.new(:id => "myobj", :pool => pool)
20
+ o.position.should == 0
21
+ o.write("data")
22
+ o.position.should == 4
23
+ end
24
+
25
+ it "should read from the current position" do
26
+ pool = a_pool
27
+ pool.should_receive(:write).and_return(4)
28
+ pool.should_receive(:read).with("myobj", { :offset => 4 }).and_return("moredata")
29
+ o = Rados::Object.new(:id => "myobj", :pool => pool)
30
+ o.write("data")
31
+ o.read.should == "moredata"
32
+ o.position.should == 12
33
+ end
34
+
35
+ it "should seek to the given position in IO:SEEK_SET mode by default" do
36
+ o = Rados::Object.new(:id => "myobj")
37
+ o.position.should == 0
38
+ o.seek(31337)
39
+ o.position.should == 31337
40
+ end
41
+
42
+ it "should seek by the given amount in IO:SEEK_CUR mode" do
43
+ o = Rados::Object.new(:id => "myobj")
44
+ o.position.should == 0
45
+ o.seek(100, IO::SEEK_CUR)
46
+ o.seek(100, IO::SEEK_CUR)
47
+ o.position.should == 200
48
+ o.seek(-50, IO::SEEK_CUR)
49
+ o.position.should == 150
50
+ end
51
+
52
+
53
+ end
@@ -0,0 +1,143 @@
1
+ require File.join(File.dirname(__FILE__), '../lib/rados')
2
+ include Rados
3
+
4
+ describe Pool do
5
+ def a_pool_name #:nodoc:
6
+ "pool-#{rand(0xffffffff).to_s(36)}"
7
+ end
8
+
9
+ def an_oid #:nodoc:
10
+ "oid-#{rand(0xffffffff).to_s(36)}"
11
+ end
12
+
13
+ def a_pool #:nodoc:
14
+ Pool.create(a_pool_name)
15
+ end
16
+
17
+ before(:all) do
18
+ Rados::initialize
19
+ end
20
+
21
+ describe "#find" do
22
+ it "should raise an error when finding a non-existant pool" do
23
+ lambda { Pool.find("no existy") }.should raise_error Rados::PoolNotFound
24
+ end
25
+ end
26
+
27
+ describe "#create" do
28
+ it "should create and return a pool" do
29
+ name = a_pool_name
30
+ pool = Pool.create name
31
+ pool.name.should == name
32
+ Pool.find(name).name.should == name
33
+ pool.destroy
34
+ end
35
+ end
36
+
37
+ describe "#destroy" do
38
+ it "should destroy an existing pool" do
39
+ pool = a_pool
40
+ pool.destroy.should == pool
41
+ pool.destroyed?.should == true
42
+ lambda { Pool.find(pool.name) }.should raise_error Rados::PoolNotFound
43
+ end
44
+ end
45
+
46
+ describe "#write" do
47
+ before(:all) do
48
+ @pool = a_pool
49
+ end
50
+
51
+ after(:all) do
52
+ @pool.destroy
53
+ end
54
+
55
+ it "should return the number of bytes written" do
56
+ oid = an_oid
57
+ @pool.write(oid, "hello world").should == "hello world".size
58
+ @pool.read(oid).should == "hello world"
59
+ end
60
+
61
+ it "should write strings with null characters in them" do
62
+ oid = an_oid
63
+ @pool.write(oid, "1234\0006789", :size => 9).should == 9
64
+ buf = @pool.read(oid)
65
+ buf.should == "1234\0006789"
66
+ buf.size.should == 9
67
+ buf[4].ord.should == 0
68
+ end
69
+
70
+ it "should write at a specified offset" do
71
+ oid = an_oid
72
+ @pool.write(oid, "123456789")
73
+ @pool.write(oid, "abcde", :offset => 3)
74
+ @pool.read(oid).should == "123abcde9"
75
+ end
76
+
77
+ it "should write the specified size" do
78
+ oid = an_oid
79
+ @pool.write(oid, "123456789")
80
+ @pool.write(oid, "aaaaaaaaa", :size => 5)
81
+ @pool.read(oid).should == "aaaaa6789"
82
+ end
83
+ end
84
+
85
+ describe "#read" do
86
+ before(:all) do
87
+ @pool = a_pool
88
+ end
89
+
90
+ after(:all) do
91
+ @pool.destroy
92
+ end
93
+
94
+ it "should return a string with the data read" do
95
+ oid = an_oid
96
+ @pool.write(oid, "hello world")
97
+ @pool.read(oid).should == "hello world"
98
+ end
99
+
100
+ it "should raise ObjectNotFound when reading an oid that doesn't exist" do
101
+ lambda { @pool.read(an_oid) }.should raise_error Rados::ObjectNotFound
102
+ end
103
+
104
+ it "should read from the specified offset" do
105
+ oid = an_oid
106
+ @pool.write(oid, "123456789")
107
+ @pool.read(oid, :offset => 3).should == "456789"
108
+ end
109
+
110
+ it "should read the specified size" do
111
+ oid = an_oid
112
+ @pool.write(oid, "123456789")
113
+ @pool.read(oid, :size => 5).should == "12345"
114
+ end
115
+ end
116
+
117
+ describe "#remove" do
118
+ before(:all) do
119
+ @pool = a_pool
120
+ end
121
+
122
+ after(:all) do
123
+ @pool.destroy
124
+ end
125
+
126
+ it "should remove the specified oid" do
127
+ oid = an_oid
128
+ @pool.write(oid, "hello world")
129
+ @pool.remove(oid)
130
+ lambda { @pool.read(oid) }.should raise_error Rados::ObjectNotFound
131
+ end
132
+
133
+ end
134
+
135
+ describe "#objects" do
136
+ it "should be an instance of ObjectCollection with this pool" do
137
+ pool = Pool.new("testpool")
138
+ pool.objects.should be_a_kind_of ObjectCollection
139
+ pool.objects.pool.should == pool
140
+ end
141
+ end
142
+
143
+ end
metadata ADDED
@@ -0,0 +1,86 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: desperados
3
+ version: !ruby/object:Gem::Version
4
+ prerelease: false
5
+ segments:
6
+ - 0
7
+ - 1
8
+ version: "0.1"
9
+ platform: ruby
10
+ authors:
11
+ - John Leach
12
+ autorequire:
13
+ bindir: bin
14
+ cert_chain: []
15
+
16
+ date: 2011-01-23 00:00:00 +00:00
17
+ default_executable:
18
+ dependencies:
19
+ - !ruby/object:Gem::Dependency
20
+ name: ffi
21
+ prerelease: false
22
+ requirement: &id001 !ruby/object:Gem::Requirement
23
+ none: false
24
+ requirements:
25
+ - - ~>
26
+ - !ruby/object:Gem::Version
27
+ segments:
28
+ - 1
29
+ - 0
30
+ - 0
31
+ version: 1.0.0
32
+ type: :runtime
33
+ version_requirements: *id001
34
+ description: "Ruby library for Ceph's Reliable Autonomic Distributed Object Store. Wraps the C++ librados library with Ruby love. "
35
+ email:
36
+ - john@johnleach.co.uk.co.uk
37
+ executables: []
38
+
39
+ extensions: []
40
+
41
+ extra_rdoc_files: []
42
+
43
+ files:
44
+ - LICENSE
45
+ - README.rdoc
46
+ - Rakefile
47
+ - desperados.gemspec
48
+ - examples/rados-load.rb
49
+ - lib/rados.rb
50
+ - spec/object_collection_spec.rb
51
+ - spec/object_spec.rb
52
+ - spec/pool_spec.rb
53
+ has_rdoc: true
54
+ homepage: https://github.com/johnl/desperados
55
+ licenses: []
56
+
57
+ post_install_message:
58
+ rdoc_options: []
59
+
60
+ require_paths:
61
+ - lib
62
+ required_ruby_version: !ruby/object:Gem::Requirement
63
+ none: false
64
+ requirements:
65
+ - - ">="
66
+ - !ruby/object:Gem::Version
67
+ segments:
68
+ - 0
69
+ version: "0"
70
+ required_rubygems_version: !ruby/object:Gem::Requirement
71
+ none: false
72
+ requirements:
73
+ - - ">="
74
+ - !ruby/object:Gem::Version
75
+ segments:
76
+ - 0
77
+ version: "0"
78
+ requirements: []
79
+
80
+ rubyforge_project:
81
+ rubygems_version: 1.3.7
82
+ signing_key:
83
+ specification_version: 3
84
+ summary: Ruby library for interacting with Ceph's RADOS
85
+ test_files: []
86
+