fire_and_forget 0.1.2 → 0.2.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (58) hide show
  1. data/Gemfile.lock +0 -8
  2. data/README.rdoc +75 -14
  3. data/bin/fire_forget +45 -22
  4. data/examples/long_task +27 -16
  5. data/fire_and_forget.gemspec +41 -4
  6. data/lib/fire_and_forget/client.rb +1 -1
  7. data/lib/fire_and_forget/command/fire.rb +23 -4
  8. data/lib/fire_and_forget/command/get_pid.rb +20 -0
  9. data/lib/fire_and_forget/command/set_pid.rb +0 -2
  10. data/lib/fire_and_forget/command/set_status.rb +1 -1
  11. data/lib/fire_and_forget/command.rb +11 -0
  12. data/lib/fire_and_forget/config.rb +3 -8
  13. data/lib/fire_and_forget/daemon.rb +14 -23
  14. data/lib/fire_and_forget/errors.rb +8 -0
  15. data/lib/fire_and_forget/launcher.rb +69 -6
  16. data/lib/fire_and_forget/server.rb +5 -1
  17. data/lib/fire_and_forget/task_description.rb +11 -0
  18. data/lib/fire_and_forget/utilities.rb +4 -4
  19. data/lib/fire_and_forget/version.rb +1 -1
  20. data/lib/fire_and_forget.rb +6 -2
  21. data/test/test_fire_and_forget.rb +59 -26
  22. data/vendor/daemons-1.1.0/LICENSE +29 -0
  23. data/vendor/daemons-1.1.0/README +224 -0
  24. data/vendor/daemons-1.1.0/Rakefile +88 -0
  25. data/vendor/daemons-1.1.0/Releases +152 -0
  26. data/vendor/daemons-1.1.0/TODO +2 -0
  27. data/vendor/daemons-1.1.0/lib/daemons/application.rb +468 -0
  28. data/vendor/daemons-1.1.0/lib/daemons/application_group.rb +194 -0
  29. data/vendor/daemons-1.1.0/lib/daemons/change_privilege.rb +19 -0
  30. data/vendor/daemons-1.1.0/lib/daemons/cmdline.rb +124 -0
  31. data/vendor/daemons-1.1.0/lib/daemons/controller.rb +140 -0
  32. data/vendor/daemons-1.1.0/lib/daemons/daemonize.rb +271 -0
  33. data/vendor/daemons-1.1.0/lib/daemons/etc_extension.rb +12 -0
  34. data/vendor/daemons-1.1.0/lib/daemons/exceptions.rb +28 -0
  35. data/vendor/daemons-1.1.0/lib/daemons/monitor.rb +138 -0
  36. data/vendor/daemons-1.1.0/lib/daemons/pid.rb +109 -0
  37. data/vendor/daemons-1.1.0/lib/daemons/pidfile.rb +116 -0
  38. data/vendor/daemons-1.1.0/lib/daemons/pidmem.rb +19 -0
  39. data/vendor/daemons-1.1.0/lib/daemons.rb +288 -0
  40. data/vendor/daemons-1.1.0/setup.rb +1360 -0
  41. data/vendor/json-1.5.0/COPYING +58 -0
  42. data/vendor/json-1.5.0/GPL +340 -0
  43. data/vendor/json-1.5.0/README +356 -0
  44. data/vendor/json-1.5.0/README-json-jruby.markdown +33 -0
  45. data/vendor/json-1.5.0/Rakefile +397 -0
  46. data/vendor/json-1.5.0/TODO +1 -0
  47. data/vendor/json-1.5.0/VERSION +1 -0
  48. data/vendor/json-1.5.0/lib/json/add/core.rb +147 -0
  49. data/vendor/json-1.5.0/lib/json/add/rails.rb +8 -0
  50. data/vendor/json-1.5.0/lib/json/common.rb +419 -0
  51. data/vendor/json-1.5.0/lib/json/editor.rb +1369 -0
  52. data/vendor/json-1.5.0/lib/json/pure/generator.rb +441 -0
  53. data/vendor/json-1.5.0/lib/json/pure/parser.rb +320 -0
  54. data/vendor/json-1.5.0/lib/json/pure.rb +15 -0
  55. data/vendor/json-1.5.0/lib/json/version.rb +8 -0
  56. data/vendor/json-1.5.0/lib/json.rb +10 -0
  57. metadata +41 -4
  58. data/lib/fire_and_forget/task.rb +0 -11
@@ -0,0 +1,356 @@
1
+ == Description
2
+
3
+ This is a implementation of the JSON specification according to RFC 4627
4
+ http://www.ietf.org/rfc/rfc4627.txt . Starting from version 1.0.0 on there
5
+ will be two variants available:
6
+
7
+ * A pure ruby variant, that relies on the iconv and the stringscan
8
+ extensions, which are both part of the ruby standard library.
9
+ * The quite a bit faster C extension variant, which is in parts implemented
10
+ in C and comes with its own unicode conversion functions and a parser
11
+ generated by the ragel state machine compiler
12
+ http://www.cs.queensu.ca/~thurston/ragel .
13
+
14
+ Both variants of the JSON generator generate UTF-8 character sequences by
15
+ default. If an :ascii_only option with a true value is given, they escape all
16
+ non-ASCII and control characters with \uXXXX escape sequences, and support
17
+ UTF-16 surrogate pairs in order to be able to generate the whole range of
18
+ unicode code points.
19
+
20
+ All strings, that are to be encoded as JSON strings, should be UTF-8 byte
21
+ sequences on the Ruby side. To encode raw binary strings, that aren't UTF-8
22
+ encoded, please use the to_json_raw_object method of String (which produces
23
+ an object, that contains a byte array) and decode the result on the receiving
24
+ endpoint.
25
+
26
+ The JSON parsers can parse UTF-8, UTF-16BE, UTF-16LE, UTF-32BE, and UTF-32LE
27
+ JSON documents under Ruby 1.8. Under Ruby 1.9 they take advantage of Ruby's
28
+ M17n features and can parse all documents which have the correct
29
+ String#encoding set. If a document string has ASCII-8BIT as an encoding the
30
+ parser attempts to figure out which of the UTF encodings from above it is and
31
+ trys to parse it.
32
+
33
+ == Installation
34
+
35
+ It's recommended to use the extension variant of JSON, because it's faster than
36
+ the pure ruby variant. If you cannot build it on your system, you can settle
37
+ for the latter.
38
+
39
+ Just type into the command line as root:
40
+
41
+ # rake install
42
+
43
+ The above command will build the extensions and install them on your system.
44
+
45
+ # rake install_pure
46
+
47
+ or
48
+
49
+ # ruby install.rb
50
+
51
+ will just install the pure ruby implementation of JSON.
52
+
53
+ If you use Rubygems you can type
54
+
55
+ # gem install json
56
+
57
+ instead, to install the newest JSON version.
58
+
59
+ There is also a pure ruby json only variant of the gem, that can be installed
60
+ with:
61
+
62
+ # gem install json_pure
63
+
64
+ == Compiling the extensions yourself
65
+
66
+ If you want to build the extensions yourself you need rake:
67
+
68
+ You can get it from rubyforge:
69
+ http://rubyforge.org/projects/rake
70
+
71
+ or just type
72
+
73
+ # gem install rake
74
+
75
+ for the installation via rubygems.
76
+
77
+ If you want to create the parser.c file from its parser.rl file or draw nice
78
+ graphviz images of the state machines, you need ragel from: http://www.cs.queensu.ca/~thurston/ragel
79
+
80
+
81
+ == Usage
82
+
83
+ To use JSON you can
84
+ require 'json'
85
+ to load the installed variant (either the extension 'json' or the pure
86
+ variant 'json_pure'). If you have installed the extension variant, you can
87
+ pick either the extension variant or the pure variant by typing
88
+ require 'json/ext'
89
+ or
90
+ require 'json/pure'
91
+
92
+ Now you can parse a JSON document into a ruby data structure by calling
93
+
94
+ JSON.parse(document)
95
+
96
+ If you want to generate a JSON document from a ruby data structure call
97
+ JSON.generate(data)
98
+
99
+ You can also use the pretty_generate method (which formats the output more
100
+ verbosely and nicely) or fast_generate (which doesn't do any of the security
101
+ checks generate performs, e. g. nesting deepness checks).
102
+
103
+ To create a valid JSON document you have to make sure, that the output is
104
+ embedded in either a JSON array [] or a JSON object {}. The easiest way to do
105
+ this, is by putting your values in a Ruby Array or Hash instance.
106
+
107
+ There are also the JSON and JSON[] methods which use parse on a String or
108
+ generate a JSON document from an array or hash:
109
+
110
+ document = JSON 'test' => 23 # => "{\"test\":23}"
111
+ document = JSON['test'] => 23 # => "{\"test\":23}"
112
+
113
+ and
114
+
115
+ data = JSON '{"test":23}' # => {"test"=>23}
116
+ data = JSON['{"test":23}'] # => {"test"=>23}
117
+
118
+ You can choose to load a set of common additions to ruby core's objects if
119
+ you
120
+ require 'json/add/core'
121
+
122
+ After requiring this you can, e. g., serialise/deserialise Ruby ranges:
123
+
124
+ JSON JSON(1..10) # => 1..10
125
+
126
+ To find out how to add JSON support to other or your own classes, read the
127
+ section "More Examples" below.
128
+
129
+ To get the best compatibility to rails' JSON implementation, you can
130
+ require 'json/add/rails'
131
+
132
+ Both of the additions attempt to require 'json' (like above) first, if it has
133
+ not been required yet.
134
+
135
+ == More Examples
136
+
137
+ To create a JSON document from a ruby data structure, you can call
138
+ JSON.generate like that:
139
+
140
+ json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
141
+ # => "[1,2,{\"a\":3.141},false,true,null,\"4..10\"]"
142
+
143
+ To get back a ruby data structure from a JSON document, you have to call
144
+ JSON.parse on it:
145
+
146
+ JSON.parse json
147
+ # => [1, 2, {"a"=>3.141}, false, true, nil, "4..10"]
148
+
149
+ Note, that the range from the original data structure is a simple
150
+ string now. The reason for this is, that JSON doesn't support ranges
151
+ or arbitrary classes. In this case the json library falls back to call
152
+ Object#to_json, which is the same as #to_s.to_json.
153
+
154
+ It's possible to add JSON support serialization to arbitrary classes by
155
+ simply implementing a more specialized version of the #to_json method, that
156
+ should return a JSON object (a hash converted to JSON with #to_json) like
157
+ this (don't forget the *a for all the arguments):
158
+
159
+ class Range
160
+ def to_json(*a)
161
+ {
162
+ 'json_class' => self.class.name, # = 'Range'
163
+ 'data' => [ first, last, exclude_end? ]
164
+ }.to_json(*a)
165
+ end
166
+ end
167
+
168
+ The hash key 'json_class' is the class, that will be asked to deserialise the
169
+ JSON representation later. In this case it's 'Range', but any namespace of
170
+ the form 'A::B' or '::A::B' will do. All other keys are arbitrary and can be
171
+ used to store the necessary data to configure the object to be deserialised.
172
+
173
+ If a the key 'json_class' is found in a JSON object, the JSON parser checks
174
+ if the given class responds to the json_create class method. If so, it is
175
+ called with the JSON object converted to a Ruby hash. So a range can
176
+ be deserialised by implementing Range.json_create like this:
177
+
178
+ class Range
179
+ def self.json_create(o)
180
+ new(*o['data'])
181
+ end
182
+ end
183
+
184
+ Now it possible to serialise/deserialise ranges as well:
185
+
186
+ json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
187
+ # => "[1,2,{\"a\":3.141},false,true,null,{\"json_class\":\"Range\",\"data\":[4,10,false]}]"
188
+ JSON.parse json
189
+ # => [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
190
+
191
+ JSON.generate always creates the shortest possible string representation of a
192
+ ruby data structure in one line. This is good for data storage or network
193
+ protocols, but not so good for humans to read. Fortunately there's also
194
+ JSON.pretty_generate (or JSON.pretty_generate) that creates a more readable
195
+ output:
196
+
197
+ puts JSON.pretty_generate([1, 2, {"a"=>3.141}, false, true, nil, 4..10])
198
+ [
199
+ 1,
200
+ 2,
201
+ {
202
+ "a": 3.141
203
+ },
204
+ false,
205
+ true,
206
+ null,
207
+ {
208
+ "json_class": "Range",
209
+ "data": [
210
+ 4,
211
+ 10,
212
+ false
213
+ ]
214
+ }
215
+ ]
216
+
217
+ There are also the methods Kernel#j for generate, and Kernel#jj for
218
+ pretty_generate output to the console, that work analogous to Core Ruby's p and
219
+ the pp library's pp methods.
220
+
221
+ The script tools/server.rb contains a small example if you want to test, how
222
+ receiving a JSON object from a webrick server in your browser with the
223
+ javasript prototype library http://www.prototypejs.org works.
224
+
225
+ == Speed Comparisons
226
+
227
+ I have created some benchmark results (see the benchmarks/data-p4-3Ghz
228
+ subdir of the package) for the JSON-parser to estimate the speed up in the C
229
+ extension:
230
+
231
+ Comparing times (call_time_mean):
232
+ 1 ParserBenchmarkExt#parser 900 repeats:
233
+ 553.922304770 ( real) -> 21.500x
234
+ 0.001805307
235
+ 2 ParserBenchmarkYAML#parser 1000 repeats:
236
+ 224.513358139 ( real) -> 8.714x
237
+ 0.004454078
238
+ 3 ParserBenchmarkPure#parser 1000 repeats:
239
+ 26.755020642 ( real) -> 1.038x
240
+ 0.037376163
241
+ 4 ParserBenchmarkRails#parser 1000 repeats:
242
+ 25.763381731 ( real) -> 1.000x
243
+ 0.038814780
244
+ calls/sec ( time) -> speed covers
245
+ secs/call
246
+
247
+ In the table above 1 is JSON::Ext::Parser, 2 is YAML.load with YAML
248
+ compatbile JSON document, 3 is is JSON::Pure::Parser, and 4 is
249
+ ActiveSupport::JSON.decode. The ActiveSupport JSON-decoder converts the
250
+ input first to YAML and then uses the YAML-parser, the conversion seems to
251
+ slow it down so much that it is only as fast as the JSON::Pure::Parser!
252
+
253
+ If you look at the benchmark data you can see that this is mostly caused by
254
+ the frequent high outliers - the median of the Rails-parser runs is still
255
+ overall smaller than the median of the JSON::Pure::Parser runs:
256
+
257
+ Comparing times (call_time_median):
258
+ 1 ParserBenchmarkExt#parser 900 repeats:
259
+ 800.592479481 ( real) -> 26.936x
260
+ 0.001249075
261
+ 2 ParserBenchmarkYAML#parser 1000 repeats:
262
+ 271.002390644 ( real) -> 9.118x
263
+ 0.003690004
264
+ 3 ParserBenchmarkRails#parser 1000 repeats:
265
+ 30.227910865 ( real) -> 1.017x
266
+ 0.033082008
267
+ 4 ParserBenchmarkPure#parser 1000 repeats:
268
+ 29.722384421 ( real) -> 1.000x
269
+ 0.033644676
270
+ calls/sec ( time) -> speed covers
271
+ secs/call
272
+
273
+ I have benchmarked the JSON-Generator as well. This generated a few more
274
+ values, because there are different modes that also influence the achieved
275
+ speed:
276
+
277
+ Comparing times (call_time_mean):
278
+ 1 GeneratorBenchmarkExt#generator_fast 1000 repeats:
279
+ 547.354332608 ( real) -> 15.090x
280
+ 0.001826970
281
+ 2 GeneratorBenchmarkExt#generator_safe 1000 repeats:
282
+ 443.968212317 ( real) -> 12.240x
283
+ 0.002252414
284
+ 3 GeneratorBenchmarkExt#generator_pretty 900 repeats:
285
+ 375.104545883 ( real) -> 10.341x
286
+ 0.002665923
287
+ 4 GeneratorBenchmarkPure#generator_fast 1000 repeats:
288
+ 49.978706968 ( real) -> 1.378x
289
+ 0.020008521
290
+ 5 GeneratorBenchmarkRails#generator 1000 repeats:
291
+ 38.531868759 ( real) -> 1.062x
292
+ 0.025952543
293
+ 6 GeneratorBenchmarkPure#generator_safe 1000 repeats:
294
+ 36.927649925 ( real) -> 1.018x 7 (>=3859)
295
+ 0.027079979
296
+ 7 GeneratorBenchmarkPure#generator_pretty 1000 repeats:
297
+ 36.272134441 ( real) -> 1.000x 6 (>=3859)
298
+ 0.027569373
299
+ calls/sec ( time) -> speed covers
300
+ secs/call
301
+
302
+ In the table above 1-3 are JSON::Ext::Generator methods. 4, 6, and 7 are
303
+ JSON::Pure::Generator methods and 5 is the Rails JSON generator. It is now a
304
+ bit faster than the generator_safe and generator_pretty methods of the pure
305
+ variant but slower than the others.
306
+
307
+ To achieve the fastest JSON document output, you can use the fast_generate
308
+ method. Beware, that this will disable the checking for circular Ruby data
309
+ structures, which may cause JSON to go into an infinite loop.
310
+
311
+ Here are the median comparisons for completeness' sake:
312
+
313
+ Comparing times (call_time_median):
314
+ 1 GeneratorBenchmarkExt#generator_fast 1000 repeats:
315
+ 708.258020939 ( real) -> 16.547x
316
+ 0.001411915
317
+ 2 GeneratorBenchmarkExt#generator_safe 1000 repeats:
318
+ 569.105020353 ( real) -> 13.296x
319
+ 0.001757145
320
+ 3 GeneratorBenchmarkExt#generator_pretty 900 repeats:
321
+ 482.825371244 ( real) -> 11.280x
322
+ 0.002071142
323
+ 4 GeneratorBenchmarkPure#generator_fast 1000 repeats:
324
+ 62.717626652 ( real) -> 1.465x
325
+ 0.015944481
326
+ 5 GeneratorBenchmarkRails#generator 1000 repeats:
327
+ 43.965681162 ( real) -> 1.027x
328
+ 0.022745013
329
+ 6 GeneratorBenchmarkPure#generator_safe 1000 repeats:
330
+ 43.929073409 ( real) -> 1.026x 7 (>=3859)
331
+ 0.022763968
332
+ 7 GeneratorBenchmarkPure#generator_pretty 1000 repeats:
333
+ 42.802514491 ( real) -> 1.000x 6 (>=3859)
334
+ 0.023363113
335
+ calls/sec ( time) -> speed covers
336
+ secs/call
337
+
338
+ == Author
339
+
340
+ Florian Frank <mailto:flori@ping.de>
341
+
342
+ == License
343
+
344
+ Ruby License, see the COPYING file included in the source distribution. The
345
+ Ruby License includes the GNU General Public License (GPL), Version 2, so see
346
+ the file GPL as well.
347
+
348
+ == Download
349
+
350
+ The latest version of this library can be downloaded at
351
+
352
+ * http://rubyforge.org/frs?group_id=953
353
+
354
+ Online Documentation should be located at
355
+
356
+ * http://json.rubyforge.org
@@ -0,0 +1,33 @@
1
+ JSON-JRuby
2
+ ==========
3
+
4
+ JSON-JRuby is a port of Florian Frank's native
5
+ [`json` library](http://json.rubyforge.org/) to JRuby.
6
+ It aims to be a perfect drop-in replacement for `json_pure`.
7
+
8
+
9
+ Development version
10
+ ===================
11
+
12
+ The latest version is available from the
13
+ [Git repository](http://github.com/mernen/json-jruby/tree):
14
+
15
+ git clone git://github.com/mernen/json-jruby.git
16
+
17
+
18
+ Compiling
19
+ =========
20
+
21
+ You'll need JRuby version 1.2 or greater to build JSON-JRuby.
22
+ Its path must be set on the `jruby.dir` property of
23
+ `nbproject/project.properties` (defaults to `../jruby`).
24
+
25
+ Additionally, you'll need [Ant](http://ant.apache.org/), and
26
+ [Ragel](http://www.cs.queensu.ca/~thurston/ragel/) 6.4 or greater.
27
+
28
+ Then, from the folder where the sources are located, type:
29
+
30
+ ant clean jar
31
+
32
+ to clean any leftovers from previous builds and generate the `.jar` files.
33
+ To generate a RubyGem, specify the `gem` action rather than `jar`.