mdp 0.1

data/.gitignore

@@ -0,0 +1,19 @@
+.libs/*
+.rbx/*
+*.rbc
+*.lo
+*.la
+*.lai
+*.dylib.dSYM
+*.dylib
+*.o
+*.a
+*.log
+tmp/*
+true/*
+*.bundle
+*.gem
+doc/*
+.DS_Store
+pkg
+ext/majordomo/Makefile

data/CHANGELOG.rdoc

@@ -0,0 +1,4 @@
+= Changelog
+
+== 0.1 ( September 06, 2012)
+* Initial public release

data/Gemfile

@@ -0,0 +1,5 @@
+source :rubygems
+
+gemspec
+
+gem 'rake'

data/Gemfile.lock

@@ -0,0 +1,19 @@
+PATH
+  remote: .
+  specs:
+    majordomo (0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    rake (0.9.2.2)
+    rake-compiler (0.8.1)
+      rake
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  majordomo!
+  rake
+  rake-compiler (~> 0.8.0)

data/README.rdoc

@@ -0,0 +1,158 @@
+= Majordomo - A Ruby binding for libmdp (Majordomo implementation in C)
+
+(c) 2012 Lourens Naudé (methodmissing), with README guidance and content from the Majordomo Protocol 0.2 spec (http://rfc.zeromq.org/spec:18)
+
+  http://github.com/methodmissing/majordomo_ruby
+
+== What is Majordomo ?
+
+The Majordomo Protocol (MDP) defines a reliable service-oriented request-reply dialog between :
+
+* a set of clients
+* a broker
+* a set of workers
+
+MDP covers presence, heartbeating and service-oriented request-reply processing. This extension implements MDP version 0.2, which adds support for multiple replies for a single request (http://rfc.zeromq.org/spec:18).
+
+== Why should I use it ?
+
+The goals of MDP are to:
+
+* Allow requests to be routed to workers on the basis of abstract service names.
+* Allow both peers to detect disconnection of the other peer, through the use of heartbeating.
+* Allow the broker to implement a "least recently used" pattern for task distribution to workers for a given service.
+* Allow the broker to recover from dead or disconnected workers by resending requests to other workers.
+
+== What are clients and workers ?
+
+Clients are applications that issue requests. Workers process them and are idempotent, thus it is safe to execute the same request more than once. Workers will handle at most one request a time, and will issue exactly one reply for each successful request.
+
+== Reliability
+
+The Majordomo pattern is designed to extend the basic ØMQ request-reply pattern with the ability to detect and recover from a specific set of failures:
+
+* Worker applications which crash, run too slowly, or freeze.
+* Worker applications that are disconnected from the network (temporarily or permanently).
+* Client applications that are temporarily disconnected from the network.
+* A queue broker that crashes and is restarted.
+* A queue broker that suffers a permanent failure.
+* Requests or replies that are lost due to any of these failures.
+
+== Scalability and Performance
+
+Majordomo is designed to be scalable to large numbers (thousands) of workers and clients, limited only by system resources on the broker. Partitioning of workers by service allows for multiple applications to share the same broker infrastructure.
+
+== Usage
+
+==== Start the broker
+
+    Lourenss-MacBook-Air:src lourens$ mdp_broker -v
+    12-09-06 02:05:06 I: MDP broker/0.2.0 is active at tcp://*:5555
+
+==== Start a worker
+
+    2.0.0dev :001 > require 'majordomo'
+     => true 
+    2.0.0dev :002 > w = Majordomo::Worker.new("tcp://localhost:5555", "service", true)
+    12-09-06 02:02:45 I: connecting to broker at tcp://localhost:5555...
+    12-09-06 02:02:45 I: sending READY to broker
+    --------------------------------------
+    [000] 
+    [006] MDPW0X
+    [001] 01
+    [007] service
+     => #<Majordomo::Worker:0x007fc533927840> 
+    2.0.0dev :003 > w.recv
+    12-09-06 02:03:06 I: received message from broker:
+    --------------------------------------
+    [000] 
+    [006] MDPW0X
+    [001] 04
+    12-09-06 02:03:06 I: sending HEARTBEAT to broker
+    --------------------------------------
+    [000] 
+    [006] MDPW0X
+    [001] 04
+    12-09-06 02:03:06 I: received message from broker:
+    --------------------------------------
+    [000] 
+    [006] MDPW0X
+    [001] 04
+    12-09-06 02:03:06 I: received message from broker:
+    --------------------------------------
+    [000] 
+    [006] MDPW0X
+    [001] 04
+    12-09-06 02:03:06 I: received message from broker:
+    --------------------------------------
+    [000] 
+    [006] MDPW0X
+    [001] 05
+    12-09-06 02:03:06 I: connecting to broker at tcp://localhost:5555...
+    12-09-06 02:03:06 I: sending READY to broker
+    --------------------------------------
+    [000] 
+    [006] MDPW0X
+    [001] 01
+    [007] service
+
+==== Start a client
+
+    2.0.0dev :001 > require 'majordomo'
+     => true 
+    2.0.0dev :002 > c = Majordomo::Client.new("tcp://localhost:5555", true)
+    12-09-06 02:00:11 I: connecting to broker at tcp://localhost:5555...
+     => #<Majordomo::Client:0x007ffc738d71c0> 
+    2.0.0dev :003 > c.send("service", "message")
+    12-09-06 02:00:26 I: send request to 'service' service:
+    --------------------------------------
+    [000] 
+    [006] MDPC0X
+    [007] service
+    [007] message
+     => true
+
+See the test/ folder for further use cases - runnable examples forthcoming.
+
+== Resources
+
+* ZeroMQ - http://www.zeromq.org/community
+* CZMQ - http://czmq.zeromq.org/
+* The Majordomo pattern - http://zguide.zeromq.org/page:all#Service-Oriented-Reliable-Queuing-Majordomo-Pattern
+* Majordomo protocol - http://rfc.zeromq.org/spec:7
+* Majordomo protocol 0.2 - http://rfc.zeromq.org/spec:18
+
+== Requirements
+
+* A POSIX compliant OS, known to work well on Linux, BSD variants and Mac OS X
+* Ruby MRI 1.8, 1.9, 2.x or Rubinius (JRuby capi support is deprecated)
+* A C compiler
+* ZeroMQ - http://www.zeromq.org/intro:get-the-software
+* CZMQ - http://czmq.zeromq.org/
+* libmdp - https://github.com/zeromq/majordomo
+
+== Installation
+
+Rubygems installation
+
+    gem install mdp
+
+Building from source
+
+    git clone git@github.com:methodmissing/majordomo_ruby
+    rake
+
+Running tests
+
+    rake test
+
+OS X notes:
+
+If you are installing ZeroMQ and CZMQ on a new Mac ensure you have libtool and autoconf installed.  
+You can get those with the brew packaging system:
+
+    brew install libtool autoconf automake
+
+== Contact, feedback and bugs
+
+Please log bugs and suggestions at https://github.com/methodmissing/majordomo_ruby/issues

data/Rakefile

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+require 'rubygems' unless defined?(Gem)
+require 'rake' unless defined?(Rake)
+
+# Prefer compiled Rubinius bytecode in .rbx/
+ENV["RBXOPT"] = "-Xrbc.db"
+
+require 'rake/extensiontask'
+require 'rake/testtask'
+
+begin
+require 'rdoc/task'
+rescue LoadError # fallback to older 1.8.7 rubies
+require 'rake/rdoctask'
+end
+
+gemspec = eval(IO.read('mdp.gemspec'))
+
+Gem::PackageTask.new(gemspec) do |pkg|
+end
+
+Rake::ExtensionTask.new('majordomo', gemspec) do |ext|
+  ext.name = 'majordomo_ext'
+  ext.ext_dir = 'ext/majordomo'
+
+  CLEAN.include 'lib/**/majordomo_ext.*'
+end
+
+desc 'Run Majordomo tests'
+Rake::TestTask.new(:test) do |t|
+  t.test_files = Dir.glob("test/**/test_*.rb")
+  t.verbose = true
+  t.warning = true
+end
+
+Rake::RDocTask.new do |rd|
+  files = FileList["README.rdoc", "ext/majordomo/*.c"]
+  rd.title = "A Ruby binding for libmd (Majordomo implementation in C)"
+  rd.main = "README.rdoc"
+  rd.rdoc_dir = "doc"
+  rd.options << "--promiscuous"
+  rd.rdoc_files.include(files)
+end
+
+task :test => :compile
+task :default => :test

data/ext/majordomo/client.c

@@ -0,0 +1,302 @@
+#include "majordomo_ext.h"
+
+VALUE rb_cMajordomoClient;
+
+/*
+ * :nodoc:
+ *  GC mark callback
+ *
+*/
+static void rb_mark_majordomo_client(void *ptr)
+{
+    rb_majordomo_client_t *client = (rb_majordomo_client_t *)ptr;
+    if (client) {
+        rb_gc_mark(client->broker);
+        rb_gc_mark(client->timeout);
+    }
+}
+
+/*
+ * :nodoc:
+ *  Release the GIL when closing a Majordomo client
+ *
+*/
+static VALUE rb_nogvl_mdp_client_close(void *ptr)
+{
+    mdp_client_t *client = ptr;
+    mdp_client_destroy(&client);
+    return Qnil;
+}
+
+/*
+ * :nodoc:
+ *  GC free callback
+ *
+*/
+static void rb_free_majordomo_client(void *ptr)
+{
+    rb_majordomo_client_t *client = (rb_majordomo_client_t *)ptr;
+    if (client) {
+        if (client->client) rb_thread_blocking_region(rb_nogvl_mdp_client_close, (void *)client->client, RUBY_UBF_IO, 0);
+#ifndef HAVE_RB_THREAD_BLOCKING_REGION
+        zlist_destroy(&(client->recv_buffer));
+#endif
+        xfree(client);
+        client = NULL;
+    }
+}
+
+/*
+ * :nodoc:
+ *  Release the GIL when creating a new Majordomo client
+ *
+*/
+static VALUE rb_nogvl_mdp_client_new(void *ptr)
+{
+    struct nogvl_md_client_new_args *args = ptr;
+    return (VALUE)mdp_client_new(args->broker, args->verbose);
+}
+
+/*
+ *  call-seq:
+ *     Majordomo::Client.new("tcp://0.0.0.0:5555")       =>  Majordomo::Client
+ *     Majordomo::Client.new("tcp://0.0.0.0:5555", true) =>  Majordomo::Client
+ *
+ *  Creates a new Majordomo::Client instance. A broker URI is required and an optional verbose flag
+ *  can be passed to the initializer.
+ *
+ * === Examples
+ *     cl = Majordomo::Client.new("tcp://0.0.0.0:5555")  =>  Majordomo::Client
+ *     cl.broker                                         =>  "tcp://0.0.0.0:5555"
+ *     cl.timeout                                        =>  2500
+ *     cl.send("test", "request")                        =>  "reply"
+ *
+*/
+static VALUE rb_majordomo_client_s_new(int argc, VALUE *argv, VALUE klass)
+{
+    rb_majordomo_client_t *client = NULL;
+    struct nogvl_md_client_new_args args;
+    VALUE obj, broker, verbose;
+    rb_scan_args(argc, argv, "11", &broker, &verbose);
+    if (verbose == Qnil)
+        verbose = Qfalse;
+    Check_Type(broker, T_STRING);
+    obj = Data_Make_Struct(klass, rb_majordomo_client_t, rb_mark_majordomo_client, rb_free_majordomo_client, client);
+    args.broker = RSTRING_PTR(broker);
+    args.verbose = (verbose == Qtrue ? 1 : 0);
+    client->client = (mdp_client_t *)rb_thread_blocking_region(rb_nogvl_mdp_client_new, (void *)&args, RUBY_UBF_IO, 0);
+    client->broker = rb_str_new4(broker);
+    client->timeout = INT2NUM(MAJORDOMO_CLIENT_TIMEOUT);
+#ifndef HAVE_RB_THREAD_BLOCKING_REGION
+    client->recv_buffer = zlist_new();
+#endif
+    rb_obj_call_init(obj, 0, NULL);
+    return obj;
+}
+
+/*
+ *  call-seq:
+ *     cl.broker                                         =>  String
+ *
+ *  Returns the URI of the broker this client is connected to.
+ *
+ * === Examples
+ *     cl = Majordomo::Client.new("tcp://0.0.0.0:5555")  =>  Majordomo::Client
+ *     cl.broker                                         =>  "tcp://0.0.0.0:5555"
+ *
+*/
+static VALUE rb_majordomo_client_broker(VALUE obj){
+    GetMajordomoClient(obj);
+    return client->broker;
+}
+
+/*
+ *  call-seq:
+ *     cl.timeout                       =>  Fixnum
+ *
+ *  Returns the request timeout for this client (in msecs).
+ *
+ * === Examples
+ *     cl = Majordomo::Client.new("tcp://0.0.0.0:5555")  =>  Majordomo::Client
+ *     cl.timeout                                        =>  2500
+ *
+*/
+static VALUE rb_majordomo_client_timeout(VALUE obj){
+    GetMajordomoClient(obj);
+    return client->timeout;
+}
+
+/*
+ *  call-seq:
+ *     cl.timeout = val                                  =>  nil
+ *
+ *  Sets the request timeout for this client (in msecs).
+ *
+ * === Examples
+ *     cl = Majordomo::Client.new("tcp://0.0.0.0:5555")  =>  Majordomo::Client
+ *     cl.timeout = 100                                  =>  nil
+ *     cl.timeout                                        =>  100
+ *
+*/
+static VALUE rb_majordomo_client_timeout_equals(VALUE obj, VALUE timeout){
+    GetMajordomoClient(obj);
+    Check_Type(timeout, T_FIXNUM);
+    mdp_client_set_timeout(client->client, FIX2INT(timeout));
+    client->timeout = timeout;
+    return Qnil;
+}
+
+/*
+ * :nodoc:
+ *  Release the GIL when sending a client message
+ *
+*/
+static VALUE rb_nogvl_mdp_client_send(void *ptr)
+{
+    struct nogvl_md_client_send_args *args = ptr;
+#ifdef HAVE_RB_THREAD_BLOCKING_REGION
+    mdp_client_send(args->client, args->service, &args->request);
+#else
+    uint32_t events;
+    size_t evopt_len = sizeof (uint32_t);
+    int fd;
+    size_t fdopt_len = sizeof (int);
+    if (rb_thread_alone()) {
+        mdp_client_send(args->client, args->service, &args->request);
+        return Qnil;
+    }
+try_writable:
+    mdp_client_getsockopt (args->client, ZMQ_EVENTS, &events, &evopt_len);
+    if ((events & ZMQ_POLLOUT) == ZMQ_POLLOUT) {
+        mdp_client_send(args->client, args->service, &args->request);
+    } else {
+        mdp_client_getsockopt (args->client, ZMQ_FD, &fd, &fdopt_len);
+        rb_thread_wait_fd(fd);
+        goto try_writable;
+    }
+#endif
+    return Qnil;
+}
+
+/*
+ *  call-seq:
+ *     cl.send("service", "message")                     =>  boolean
+ *
+ *  Send a request to the broker. Returns true if the send was successful.
+ *
+ * === Examples
+ *     cl = Majordomo::Client.new("tcp://0.0.0.0:5555")  =>  Majordomo::Client
+ *     cl.send("service", "message")                     =>  true
+ *
+*/
+static VALUE rb_majordomo_client_send(VALUE obj, VALUE service, VALUE message){
+    struct nogvl_md_client_send_args args;
+    GetMajordomoClient(obj);
+    Check_Type(service, T_STRING);
+    Check_Type(message, T_STRING);
+    args.client = client->client;
+    args.service = RSTRING_PTR(service);
+    args.request = zmsg_new();
+    if (!args.request)
+        return Qfalse;
+    if (zmsg_pushstr(args.request, RSTRING_PTR(message)) != 0){
+        zmsg_destroy(&args.request);
+        return Qfalse;
+    }
+    rb_thread_blocking_region(rb_nogvl_mdp_client_send, (void *)&args, RUBY_UBF_IO, 0);
+    return Qtrue;
+}
+
+/*
+ * :nodoc:
+ *  Release the GIL when receiving a client message
+ *
+*/
+static VALUE rb_nogvl_mdp_client_recv(void *ptr)
+{
+    struct nogvl_md_client_recv_args *args = ptr;
+    rb_majordomo_client_t *client = args->client;
+#ifdef HAVE_RB_THREAD_BLOCKING_REGION
+    return (VALUE)mdp_client_recv(client->client, args->service);
+#else
+    uint32_t events;
+    size_t evopt_len = sizeof (uint32_t);
+    int fd;
+    size_t fdopt_len = sizeof (int);
+    if (zlist_size(client->recv_buffer) != 0)
+       return (VALUE)zlist_pop(client->recv_buffer);
+try_readable:
+    mdp_client_getsockopt (client->client, ZMQ_EVENTS, &events, &evopt_len);
+    if ((events & ZMQ_POLLIN) == ZMQ_POLLIN) {
+        do {
+            zlist_append(client->recv_buffer, mdp_client_recv(client->client, args->service));
+        } while (zmq_errno() != EAGAIN && zmq_errno() != EINTR);
+        return (VALUE)zlist_pop(client->recv_buffer);
+     } else {
+        mdp_client_getsockopt (client->client, ZMQ_FD, &fd, &fdopt_len);
+        rb_thread_wait_fd(fd);
+        goto try_readable;
+     }
+#endif
+}
+
+/*
+ *  call-seq:
+ *     cl.recv("service")                     =>  String or nil
+ *
+ *  Send a request to the broker and get a reply even if it has to retry several times. Valid replies are of type
+ *  String and NilClass.
+ *
+ * === Examples
+ *     cl = Majordomo::Client.new("tcp://0.0.0.0:5555")  =>  Majordomo::Client
+ *     cl.send("service", "message")                     =>  nil
+ *     cl.recv("service")                                =>  "reply"
+ *
+*/
+static VALUE rb_majordomo_client_recv(VALUE obj, VALUE service){
+    VALUE rep;
+    zmsg_t *reply = NULL;
+    struct nogvl_md_client_recv_args args;
+    GetMajordomoClient(obj);
+    Check_Type(service, T_STRING);
+    args.client = client;
+    args.service = RSTRING_PTR(service);
+    reply = (zmsg_t *)rb_thread_blocking_region(rb_nogvl_mdp_client_recv, (void *)&args, RUBY_UBF_IO, 0);
+    if (!reply)
+        return Qnil;
+    rep = MajordomoEncode(rb_str_new2(zmsg_popstr(reply)));
+    zmsg_destroy(&reply);
+    return rep;
+}
+
+/*
+ *  call-seq:
+ *     cl.close                                          =>  nil
+ *
+ *  Close the client connection to the broker.
+ *
+ * === Examples
+ *     cl = Majordomo::Client.new("tcp://0.0.0.0:5555")  =>  Majordomo::Client
+ *     cl.close                                          =>  nil
+ *
+*/
+static VALUE rb_majordomo_client_close(VALUE obj){
+    VALUE ret;
+    GetMajordomoClient(obj);
+    ret = rb_thread_blocking_region(rb_nogvl_mdp_client_close, (void *)client->client, RUBY_UBF_IO, 0);
+    client->client = NULL;
+    return ret;
+}
+
+void _init_majordomo_client()
+{
+    rb_cMajordomoClient = rb_define_class_under(rb_mMajordomo, "Client", rb_cObject);
+
+    rb_define_singleton_method(rb_cMajordomoClient, "new", rb_majordomo_client_s_new, -1);
+    rb_define_method(rb_cMajordomoClient, "broker", rb_majordomo_client_broker, 0);
+    rb_define_method(rb_cMajordomoClient, "timeout", rb_majordomo_client_timeout, 0);
+    rb_define_method(rb_cMajordomoClient, "timeout=", rb_majordomo_client_timeout_equals, 1);
+    rb_define_method(rb_cMajordomoClient, "send", rb_majordomo_client_send, 2);
+    rb_define_method(rb_cMajordomoClient, "recv", rb_majordomo_client_recv, 1);
+    rb_define_method(rb_cMajordomoClient, "close", rb_majordomo_client_close, 0);
+}