posix_mq 0.2.0 → 0.3.0

data/ChangeLog

@@ -1,5 +1,119 @@
 ChangeLog from git://git.bogomips.org/ruby_posix_mq.git ()
 
+    commit 2e420820d3b3fb228c810937539f95a618a2c271
+    Author: Eric Wong <normalperson@yhbt.net>
+    Date:   Sat Jan 9 22:52:27 2010 +0000
+    
+        posix_mq 0.3.0
+        
+        This release adds a few new API methods, fixes MRI 1.8.6
+        support.  We should now have full feature parity with
+        underlying POSIX message queue C API.
+        
+        * POSIX_MQ#notify(&block)
+          RDoc: http://bogomips.org/ruby_posix_mq/POSIX_MQ.html#M000001
+          This is only supported on platforms that implement
+          SIGEV_THREAD with mq_notify(3) (tested with glibc + Linux).
+          Other platforms will have to continue to rely on signal
+          notifications via POSIX#notify=signal, or IO notifications
+          in FreeBSD (and Linux).
+        
+        * POSIX_MQ#shift([buffer [,timeout]])
+          Shorthand for the common "POSIX_MQ#receive.first"
+          when you do not care for priority of the received message.
+        
+        Rev, EventMachine and Reactor support are planned for
+        Linux, FreeBSD and possibly any other platforms where POSIX
+        message queues are implemented with a file descriptor.
+    
+    commit 2c71257b2b95e737088726ffc963b4e72f1b5455
+    Author: Eric Wong <normalperson@yhbt.net>
+    Date:   Sat Jan 9 22:49:49 2010 +0000
+    
+        MRI 1.8 does not have rb_str_flush
+        
+        It's Rubinius-specific and we use rb_str_resize
+        there anyways...
+    
+    commit 531106e51e519458d37bed3721da4eff2f163206
+    Author: Eric Wong <normalperson@yhbt.net>
+    Date:   Fri Jan 8 11:30:49 2010 -0800
+    
+        no point in non-blocking for fd notifications
+        
+        It's not needed since the native thread will retry in the
+        unlikely case of EINTR/EAGAIN.  And writing one byte to a pipe
+        that's guaranteed by POSIX to be at least 512 bytes is highly
+        unlikely.
+        
+        It's also bad because F_SETFL takes the big kernel lock under
+        Linux (and possibly other systems), and doing it unnecessarily
+        is a waste of system cycles.
+    
+    commit d03c76ae11ca6294e05262df747e4d43822ada73
+    Author: Eric Wong <normalperson@yhbt.net>
+    Date:   Fri Jan 8 11:25:06 2010 -0800
+    
+        mode_t is usually unsigned
+        
+        Most used open modes are well under INT_MAX, however
+    
+    commit b3c31cf444e2ca3dae0f6d2370944bfbf3382d88
+    Author: Eric Wong <normalperson@yhbt.net>
+    Date:   Thu Jan 7 01:45:25 2010 -0800
+    
+        add POSIX_MQ#shift helper method
+        
+        This acts like POSIX_MQ#receive but only returns the message
+        without the priority.
+    
+    commit 3700db51399e4949ed314ad0545d037b7762064e
+    Author: Eric Wong <normalperson@yhbt.net>
+    Date:   Thu Jan 7 09:28:57 2010 +0000
+    
+        POSIX_MQ#notify only works on GNU/Linux for now
+        
+        SIGEV_THREAD is not easy to implement, so many platforms
+        do not implement it.
+    
+    commit 40d61f55ac53e3cd2f229d0b032da03032e3d53d
+    Author: Eric Wong <normalperson@yhbt.net>
+    Date:   Thu Jan 7 00:37:57 2010 -0800
+    
+        POSIX_MQ#notify block execution on message received
+        
+        This is implementation uses both a short-lived POSIX thread and
+        a pre-spawned Ruby Thread in a manner that works properly under
+        both Ruby 1.8 (green threads) and 1.9 (where Ruby Threads are
+        POSIX threads).
+        
+        The short-lived POSIX thread will write a single "\0" byte to
+        a pipe the Ruby Thread waits on.  This operation is atomic
+        on all platforms.  Once the Ruby Thread is woken up from the
+        pipe, it will execute th block given to it.
+        
+        This dual-thread implementation is inspired by the way glibc
+        implements mq_notify(3) + SIGEV_THREAD under Linux where the
+        kernel itself cannot directly spawn POSIX threads.
+    
+    commit d8c8fb4155c1feea454abc3ed3f0a4b26e90be68
+    Author: Eric Wong <normalperson@yhbt.net>
+    Date:   Sun Jan 3 05:26:00 2010 +0000
+    
+        fix warnings on platforms where mqd_t != int
+        
+        The POSIX manpages specify the return values of all
+        mq_* functions besides mq_open(3) to be "int", not "mqd_t".
+    
+    commit dbe5ed46e07b853e79e44141924a0166016e3e44
+    Author: Eric Wong <normalperson@yhbt.net>
+    Date:   Sat Jan 2 23:19:34 2010 -0800
+    
+        bump GIT-VERSION-GEN
+        
+        Shouldn't affect most people since they should just
+        take code from git...
+    
     commit fd2fcdeee6b44f7854255cb7e01c81db3cd2d99c
     Author: Eric Wong <normalperson@yhbt.net>
     Date:   Sun Jan 3 05:46:45 2010 +0000

data/GIT-VERSION-FILE

@@ -1 +1 @@
-GIT_VERSION = 0.2.0
+GIT_VERSION = 0.3.0

data/GIT-VERSION-GEN

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 GVF=GIT-VERSION-FILE
-DEF_VER=v0.1.0.GIT
+DEF_VER=v0.3.0.GIT
 
 LF='
 '

data/NEWS

@@ -1,3 +1,25 @@
+=== 0.3.0 / 2010-01-09 23:11 UTC
+
+  This release adds a few new API methods, fixes MRI 1.8.6
+  support.  We should now have full feature parity with
+  underlying POSIX message queue C API.
+
+  * POSIX_MQ#notify(&block)
+    RDoc: http://bogomips.org/ruby_posix_mq/POSIX_MQ.html#M000001
+    This is only supported on platforms that implement
+    SIGEV_THREAD with mq_notify(3) (tested with glibc + Linux).
+    Other platforms will have to continue to rely on signal
+    notifications via POSIX#notify=signal, or IO notifications
+    in FreeBSD (and Linux).
+
+  * POSIX_MQ#shift([buffer [,timeout]])
+    Shorthand for the common "POSIX_MQ#receive.first"
+    when you do not care for priority of the received message.
+
+  Rev, EventMachine and Reactor support are planned for
+  Linux, FreeBSD and possibly any other platforms where POSIX
+  message queues are implemented with a file descriptor.
+
 === 0.2.0 / 2010-01-03 05:52 UTC
 
   This release fixes notification (un)registration and should be

data/README

@@ -11,15 +11,20 @@ network-aware message queue implementations.
 
 == Features
 
-* Supports message notifications via signals.
+* Supports message notifications via signals on all platforms
 
 * Supports portable non-blocking operation.  Under Linux 2.6.6+ and
   FreeBSD 7.2+, POSIX_MQ objects may even be used with event
   notification mechanisms such as IO.select.
 
+* Supports notifications via block execution in a separate thread
+  on platforms that implement SIGEV_THREAD for mq_notify(3),
+  currently only GNU/Linux.
+
 * Optional timeouts may be applied to send and receive operations.
 
-* Thread-safe under Ruby 1.9, releases GVL before blocking operations.
+* Thread-safe blocking operations under Ruby 1.9, releases GVL
+  before blocking operations.
 
 * Documented library API
 

data/ext/posix_mq/extconf.rb

@@ -4,9 +4,11 @@ have_header("sys/select.h")
 have_header("signal.h")
 have_header("mqueue.h") or abort "mqueue.h header missing"
 have_func("__mq_oshandle")
+have_header("pthread.h")
 have_func("rb_str_set_len")
 have_func("rb_struct_alloc_noinit")
 have_func('rb_thread_blocking_region')
 have_library("rt")
+have_library("pthread")
 dir_config("posix_mq")
 create_makefile("posix_mq_ext")

data/ext/posix_mq/posix_mq.c

@@ -5,6 +5,9 @@
 #ifdef HAVE_SIGNAL_H
 #  include <signal.h>
 #endif
+#ifdef HAVE_PTHREAD_H
+#  include <pthread.h>
+#endif
 #include <ruby.h>
 
 #include <time.h>
@@ -34,13 +37,14 @@ struct posix_mq {
 	mqd_t des;
 	long msgsize;
 	VALUE name;
+	VALUE thread;
 #ifdef MQD_TO_FD
 	VALUE io;
 #endif
 };
 
 static VALUE cPOSIX_MQ, cAttr;
-static ID id_new;
+static ID id_new, id_kill, id_fileno;
 static ID sym_r, sym_w, sym_rw;
 static const mqd_t MQD_INVALID = (mqd_t)-1;
 
@@ -67,7 +71,6 @@ static void rb_18_str_set_len(VALUE str, long len)
 {
 	RSTRING(str)->len = len;
 	RSTRING(str)->ptr[len] = '\0';
-	rb_str_flush(str);
 }
 #    define rb_str_set_len(str,len) rb_18_str_set_len(str,len)
 #  endif /* ! RUBINIUS */
@@ -198,6 +201,7 @@ static void mark(void *ptr)
 	struct posix_mq *mq = ptr;
 
 	rb_gc_mark(mq->name);
+	rb_gc_mark(mq->thread);
 	MQ_IO_MARK(mq);
 }
 
@@ -225,6 +229,7 @@ static VALUE alloc(VALUE klass)
 	mq->des = MQD_INVALID;
 	mq->msgsize = -1;
 	mq->name = Qnil;
+	mq->thread = Qnil;
 	MQ_IO_SET(mq, Qnil);
 
 	return rv;
@@ -325,7 +330,7 @@ static VALUE init(int argc, VALUE *argv, VALUE self)
 	switch (TYPE(mode)) {
 	case T_FIXNUM:
 		x.argc = 3;
-		x.mode = NUM2INT(mode);
+		x.mode = NUM2UINT(mode);
 		break;
 	case T_NIL:
 		if (x.oflags & O_CREAT) {
@@ -497,12 +502,14 @@ static void get_msgsize(struct posix_mq *mq)
 {
 	struct mq_attr attr;
 
-	if (mq_getattr(mq->des, &attr) == MQD_INVALID)
+	if (mq_getattr(mq->des, &attr) < 0)
 		rb_sys_fail("mq_getattr");
 
 	mq->msgsize = attr.mq_msgsize;
 }
 
+static VALUE _receive(int wantarray, int argc, VALUE *argv, VALUE self);
+
 /*
  * call-seq:
  *	mq.receive([buffer, [timeout]])		=> [ message, priority ]
@@ -520,6 +527,31 @@ static void get_msgsize(struct posix_mq *mq)
  * in the queue.
  */
 static VALUE receive(int argc, VALUE *argv, VALUE self)
+{
+	return _receive(1, argc, argv, self);
+}
+
+/*
+ * call-seq:
+ *	mq.shift([buffer, [timeout]])		=> message
+ *
+ * Takes the highest priority message off the queue and returns
+ * the message as a String.
+ *
+ * If the optional +buffer+ is present, then it must be a String
+ * which will receive the data.
+ *
+ * If the optional +timeout+ is present, then it may be a Float
+ * or Integer specifying the timeout in seconds.  Errno::ETIMEDOUT
+ * will be raised if +timeout+ has elapsed and there are no messages
+ * in the queue.
+ */
+static VALUE shift(int argc, VALUE *argv, VALUE self)
+{
+	return _receive(0, argc, argv, self);
+}
+
+static VALUE _receive(int wantarray, int argc, VALUE *argv, VALUE self)
 {
 	struct posix_mq *mq = get(self, 1);
 	struct rw_args x;
@@ -551,7 +583,9 @@ static VALUE receive(int argc, VALUE *argv, VALUE self)
 
 	rb_str_set_len(buffer, r);
 
-	return rb_ary_new3(2, buffer, UINT2NUM(x.msg_prio));
+	if (wantarray)
+		return rb_ary_new3(2, buffer, UINT2NUM(x.msg_prio));
+	return buffer;
 }
 
 /*
@@ -569,7 +603,7 @@ static VALUE getattr(VALUE self)
 	VALUE astruct;
 	VALUE *ptr;
 
-	if (mq_getattr(mq->des, &attr) == MQD_INVALID)
+	if (mq_getattr(mq->des, &attr) < 0)
 		rb_sys_fail("mq_getattr");
 
 	astruct = rb_struct_alloc_noinit(cAttr);
@@ -599,7 +633,7 @@ static VALUE setattr(VALUE self, VALUE astruct)
 
 	attr_from_struct(&newattr, astruct, 0);
 
-	if (mq_setattr(mq->des, &newattr, NULL) == MQD_INVALID)
+	if (mq_setattr(mq->des, &newattr, NULL) < 0)
 		rb_sys_fail("mq_setattr");
 
 	return astruct;
@@ -619,7 +653,7 @@ static VALUE _close(VALUE self)
 {
 	struct posix_mq *mq = get(self, 1);
 
-	if (mq_close(mq->des) == MQD_INVALID)
+	if (mq_close(mq->des) < 0)
 		rb_sys_fail("mq_close");
 
 	mq->des = MQD_INVALID;
@@ -683,6 +717,39 @@ static int lookup_sig(VALUE sig)
 	return NUM2INT(sig);
 }
 
+/* we spawn a thread just to write ONE byte into an fd (usually a pipe) */
+static void thread_notify_fd(union sigval sv)
+{
+	int fd = sv.sival_int;
+
+	while ((write(fd, "", 1) < 0) && (errno == EINTR || errno == EAGAIN));
+}
+
+static void setup_notify_io(struct sigevent *not, VALUE io)
+{
+	VALUE fileno = rb_funcall(io, id_fileno, 0, 0);
+	int fd = NUM2INT(fileno);
+	pthread_attr_t attr;
+	int e;
+
+	if ((e = pthread_attr_init(&attr)))
+		goto err;
+	if ((e = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED)))
+		goto err;
+#ifdef PTHREAD_STACK_MIN
+	(void)pthread_attr_setstacksize(&attr, PTHREAD_STACK_MIN);
+#else
+#  warning PTHREAD_STACK_MIN not available,
+#endif
+	not->sigev_notify = SIGEV_THREAD;
+	not->sigev_notify_function = thread_notify_fd;
+	not->sigev_notify_attributes = &attr;
+	not->sigev_value.sival_int = fd;
+	return;
+err:
+	rb_raise(rb_eRuntimeError, "pthread failure: %s\n", strerror(e));
+}
+
 /*
  * call-seq:
  *	mq.notify = signal	=> signal
@@ -693,10 +760,16 @@ static int lookup_sig(VALUE sig)
  * request to allow other processes to register a request.
  * If +signal+ is +false+, it will register a no-op notification request
  * which will prevent other processes from registering a notification.
+ * If +signal+ is an +IO+ object, it will spawn a thread upon the
+ * arrival of the next message and write one "\\0" byte to the file
+ * descriptor belonging to that IO object.
  * Only one process may have a notification request for a queue
  * at a time, Errno::EBUSY will be raised if there is already
  * a notification request registration for the queue.
  *
+ * Notifications are only fired once and processes must reregister
+ * for subsequent notifications.
+ *
  * For readers of the mq_notify(3) manpage, passing +false+
  * is equivalent to SIGEV_NONE, and passing +nil+ is equivalent
  * of passing a NULL notification pointer to mq_notify(3).
@@ -708,6 +781,10 @@ static VALUE setnotify(VALUE self, VALUE arg)
 	struct sigevent * notification = &not;
 	VALUE rv = arg;
 
+	if (!NIL_P(mq->thread)) {
+		rb_funcall(mq->thread, id_kill, 0, 0);
+		mq->thread = Qnil;
+	}
 	not.sigev_notify = SIGEV_SIGNAL;
 
 	switch (TYPE(arg)) {
@@ -725,12 +802,15 @@ static VALUE setnotify(VALUE self, VALUE arg)
 		not.sigev_signo = lookup_sig(arg);
 		rv = INT2NUM(not.sigev_signo);
 		break;
+	case T_FILE:
+		setup_notify_io(&not, arg);
+		break;
 	default:
 		/* maybe support Proc+thread via sigev_notify_function.. */
 		rb_raise(rb_eArgError, "must be a signal or nil");
 	}
 
-	if (mq_notify(mq->des, notification) == MQD_INVALID)
+	if (mq_notify(mq->des, notification) < 0)
 		rb_sys_fail("mq_notify");
 
 	return rv;
@@ -747,7 +827,7 @@ static VALUE getnonblock(VALUE self)
 	struct mq_attr attr;
 	struct posix_mq *mq = get(self, 1);
 
-	if (mq_getattr(mq->des, &attr) == MQD_INVALID)
+	if (mq_getattr(mq->des, &attr) < 0)
 		rb_sys_fail("mq_getattr");
 
 	mq->msgsize = attr.mq_msgsize; /* optimization */
@@ -776,7 +856,7 @@ static VALUE setnonblock(VALUE self, VALUE nb)
 	else
 		rb_raise(rb_eArgError, "must be true or false");
 
-	if (mq_setattr(mq->des, &newattr, &oldattr) == MQD_INVALID)
+	if (mq_setattr(mq->des, &newattr, &oldattr) < 0)
 		rb_sys_fail("mq_setattr");
 
 	mq->msgsize = oldattr.mq_msgsize; /* optimization */
@@ -784,6 +864,15 @@ static VALUE setnonblock(VALUE self, VALUE nb)
 	return nb;
 }
 
+/* :nodoc: */
+static VALUE setnotifythread(VALUE self, VALUE thread)
+{
+	struct posix_mq *mq = get(self, 1);
+
+	mq->thread = thread;
+	return thread;
+}
+
 void Init_posix_mq_ext(void)
 {
 	cPOSIX_MQ = rb_define_class("POSIX_MQ", rb_cObject);
@@ -814,6 +903,7 @@ void Init_posix_mq_ext(void)
 	rb_define_method(cPOSIX_MQ, "send", _send, -1);
 	rb_define_method(cPOSIX_MQ, "<<", send0, 1);
 	rb_define_method(cPOSIX_MQ, "receive", receive, -1);
+	rb_define_method(cPOSIX_MQ, "shift", shift, -1);
 	rb_define_method(cPOSIX_MQ, "attr", getattr, 0);
 	rb_define_method(cPOSIX_MQ, "attr=", setattr, 1);
 	rb_define_method(cPOSIX_MQ, "close", _close, 0);
@@ -822,12 +912,15 @@ void Init_posix_mq_ext(void)
 	rb_define_method(cPOSIX_MQ, "name", name, 0);
 	rb_define_method(cPOSIX_MQ, "notify=", setnotify, 1);
 	rb_define_method(cPOSIX_MQ, "nonblock=", setnonblock, 1);
+	rb_define_method(cPOSIX_MQ, "notify_thread=", setnotifythread, 1);
 	rb_define_method(cPOSIX_MQ, "nonblock?", getnonblock, 0);
 #ifdef MQD_TO_FD
 	rb_define_method(cPOSIX_MQ, "to_io", to_io, 0);
 #endif
 
 	id_new = rb_intern("new");
+	id_kill = rb_intern("kill");
+	id_fileno = rb_intern("fileno");
 	sym_r = ID2SYM(rb_intern("r"));
 	sym_w = ID2SYM(rb_intern("w"));
 	sym_rw = ID2SYM(rb_intern("rw"));

data/lib/posix_mq.rb

@@ -1,8 +1,8 @@
 # -*- encoding: binary -*-
 class POSIX_MQ
 
-  # version of POSIX_MQ, currently 0.1.0
-  VERSION = '0.2.0'
+  # version of POSIX_MQ, currently 0.3.0
+  VERSION = '0.3.0'
 
   # An analogous Struct to "struct mq_attr" in C.
   # This may be used in arguments for POSIX_MQ.new and
@@ -26,9 +26,46 @@ class POSIX_MQ
         mq.close unless mq.closed?
       end
     end
-
   end
 
+  # Executes the given block upon reception of the next message in an
+  # empty queue.  If the message queue is not empty, then this block
+  # will only be fired after the queue is emptied and repopulated with
+  # one message.
+  #
+  # This block will only be executed upon the arrival of the
+  # first message and must be reset/reenabled for subsequent
+  # notifications.  This block will execute in a separate Ruby
+  # Thread (and thus will safely have the GVL by default).
+  #
+  # This method is only supported on platforms that implement
+  # SIGEV_THREAD functionality in mq_notify(3).  So far we only
+  # know of glibc + Linux supporting this.  Please let us
+  # know if your platform can support this functionality and
+  # are willing to test for us <ruby.posix.mq@librelist.com>
+  def notify(&block)
+    block.arity == 1 or
+      raise ArgumentError, "arity of notify block must be 1"
+    r, w = IO.pipe
+    thr = Thread.new(r, w, self) do |r, w, mq|
+      begin
+        begin
+          r.read(1) or raise Errno::EINTR
+        rescue Errno::EINTR, Errno::EAGAIN
+          retry
+        end
+        block.call(mq)
+      ensure
+        mq.notify_thread = nil
+        r.close rescue nil
+        w.close rescue nil
+      end
+    end
+    self.notify = w
+    self.notify_thread = thr
+    nil
+  end if RUBY_PLATFORM =~ /linux/
+
 end
 
 require 'posix_mq_ext'

data/test/test_posix_mq.rb

@@ -1,6 +1,7 @@
 # -*- encoding: binary -*-
 require 'test/unit'
 require 'posix_mq'
+require 'thread'
 require 'fcntl'
 $stderr.sync = $stdout.sync = true
 
@@ -89,6 +90,12 @@ class Test_POSIX_MQ < Test::Unit::TestCase
     assert_equal [ "world", 0 ], @mq.receive
   end
 
+  def test_shift
+    @mq = POSIX_MQ.new @path, IO::CREAT|IO::RDWR, 0666
+    @mq << "hello"
+    assert_equal "hello", @mq.shift
+  end
+
   def test_send_receive
     @mq = POSIX_MQ.new @path, IO::CREAT|IO::RDWR, 0666
     assert_nil @mq.send("hello", 0)
@@ -238,4 +245,28 @@ class Test_POSIX_MQ < Test::Unit::TestCase
     assert POSIX_MQ::OPEN_MAX.kind_of?(Integer)
   end
 
+  def test_notify_block_replace
+    q = Queue.new
+    @mq = POSIX_MQ.new(@path, :rw)
+    assert_nothing_raised { @mq.notify { |mq| q << mq } }
+    @mq << "hi"
+    assert_equal POSIX_MQ, q.pop.class
+    assert_equal "hi", @mq.receive.first
+    assert_nothing_raised { @mq.notify { |mq| q << "hi" } }
+    @mq << "bye"
+    assert_equal "hi", q.pop
+  end if POSIX_MQ.respond_to?(:notify)
+
+  def test_notify_thread
+    q = Queue.new
+    @mq = POSIX_MQ.new(@path, :rw)
+    @mq.notify_thread = thr = Thread.new { sleep }
+    assert thr.alive?
+    @mq.notify { |mq| q << Thread.current }
+    @mq << "."
+    x = q.pop
+    assert x.instance_of?(Thread)
+    assert Thread.current != x
+    assert ! thr.alive?
+  end if POSIX_MQ.respond_to?(:notify)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: posix_mq
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Ruby POSIX MQ hackers
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-03 00:00:00 +00:00
+date: 2010-01-09 00:00:00 +00:00
 default_executable: 
 dependencies: []