diff --git a/README.md b/README.md index 7d5f73c..8cbc651 100644 --- a/README.md +++ b/README.md @@ -156,8 +156,11 @@ gem install symphony-metronome ## Contributing -You can check out the current development source with Mercurial via its -[project page](http://bitbucket.org/mahlon/symphony-metronome). +You can check out the current development source with Mercurial +[here](http://code.martini.nu/symphony-metronome), or via a mirror: + + * github: https://github.com/mahlonsmith/Symphony-Metronome + * SourceHut: https://hg.sr.ht/~mahlon/Symphony-Metronome After checking out the source, run: diff --git a/README.rdoc b/README.rdoc deleted file mode 100644 index fcd500e..0000000 --- a/README.rdoc +++ /dev/null @@ -1,207 +0,0 @@ - -= metronome - -== Description - -Metronome is an interval scheduler and task runner. It can be used -locally as a cron replacement, or as a network-wide job executor. - -Events are stored via simple database rows, and optionally managed -via AMQP events. Interval/time values are expressed with intuitive -English phrases, ie.: 'at 2pm', or 'Starting in 20 minutes, run every 10 -seconds and then finish in 2 days', or 'execute 12 times during the next -minute'. - -It includes an executable under bin/: - -metronome-exp:: - A simple tester for trying out interval expression parsing. - - -== Synopsis - -Here's an example of a cron clone: - - require 'symphony/metronome' - - Symphony.load_config - - Symphony::Metronome.run do |opts, id| - Thread.new do - pid = fork { exec opts.delete('command') } - Process.waitpid( pid ) - end - end - - -And here's a simplistic AMQP message broadcaster, using existing -Symphony connection information: - - require 'symphony/metronome' - - Symphony.load_config - - Symphony::Metronome.run do |opts, id| - key = opts.delete( :routing_key ) or next - exchange = Symphony::Queue.amqp_exchange - exchange.publish( 'hi from Metronome!', routing_key: key ) - end - - -== Adding Actions - -There are two primary components to Metronome -- getting schedules into -its database, and performing some task with those actions when the time -is appropriate. - -By default, Metronome will start up an AMQP listener, attached to your -Symphony exchange, and wait for new scheduling messages. There are two -events it will take action on: - -metronome.create:: - Create a new scheduled event. The payload should be a hash. An - 'expression' key is required, that provides the interval description. - Anything additional is serialized to 'options', that are passed to the - block when the interval fires. You can populate it with anything - your task requires to execute. - -metronome.delete:: - The payload is the row ID of the action. Metronome removes it from - the database. - - -If you'd prefer not to use the AMQP listener, you can put actions into -Metronome using any database methodology you please. When the daemon -starts up or receives a HUP signal, it will re-read and schedule out -upcoming work. - - -== Performing Work - -Calling 'run' on the Metronome class is a blocking call, waking up upon -a scheduled event. The run method expects a ruby block, and it receives -the payload and the database ID of the scheduled event. Metronome is -unopinioned, what you do within this block is entirely up to you. See -the Synopsis section above for some examples. - - -== Options - -Metronome uses -Configurability[https://rubygems.org/gems/configurability] to determine -behavior. The configuration is a YAML[http://www.yaml.org/] file. It -shares AMQP configuration with Symphony, and adds metronome specific -controls in the 'metronome' key. - - metronome: - splay: 0 - listen: true - db: sqlite:///tmp/metronome.db - - -=== splay - -Randomize all start times for actions by this many seconds on either -side of the original execution time. Defaults to none. - -=== listen - -Start up an AMQP listener using Symphony configuration, for remote -administration of schedule events. Defaults to true. - -=== db - -A {Sequel}[https://rubygems.org/gems/sequel] connection URI. Currently, -Metronome is tested under SQLite and PostgreSQL. Defaults to a SQLite -file at /tmp/metronome.db. - - -== Scheduling Examples - -Note that Metronome is designed as an interval scheduler, not a -calendaring app. It doesn't have any concepts around phrases like "next -tuesday", or "the 3rd sunday after christmas". If that's what you're -after, check out the {chronic}[http://rubygems.org/gems/chronic] -library instead. - -Here are a small set of example expressions. Feel free to use the -+metronome-exp+ utility to get a feel for what Metronome anticipates. - - in 30.5 minutes - once an hour - every 15 minutes for 2 days - at 2014-05-01 - at 2014-04-01 14:00:25 - at 2pm - starting at 2pm once a day - start in 1 hour from now run every 5 seconds end at 11:15pm - every other hour - run every 7th minute for a day - once a day ending in 1 week - run once a minute for an hour starting in 6 days - 10 times a minute for 2 days - run 45 times every hour - 30 times per day - start at 2010-01-02 run 12 times and end on 2010-01-03 - starting in an hour from now run 6 times a minute for 2 hours - beginning a day from now, run 30 times per minute and finish in 2 weeks - execute 12 times during the next 2 minutes - once a minute beginning in 5 minutes - -In general, you can use reasonably intuitive phrasings. Capitalization, -whitespace, and punctuation doesn't matter. When describing numbers, -use digit/integer form instead of words, ie: '1 hour' instead of 'one -hour'. - - -== Installation - - gem install symphony-metronome - - -== Contributing - -You can check out the current development source with Mercurial via its -{project page}[http://bitbucket.org/mahlon/symphony-metronome]. - -After checking out the source, run: - - $ rake - -This task will run the tests/specs and generate the API documentation. - -If you use {rvm}[http://rvm.io/], entering the project directory will -install any required development dependencies. - - -== License - -Copyright (c) 2015, Mahlon E. Smith -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -* Neither the name of the author/s, nor the names of the project's - contributors may be used to endorse or promote products derived from this - software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -