mqueue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5f419f642dfc73f8a2e09c836decc951a51d2030
+  data.tar.gz: ac1b186869ebe184375682db89822aafbb1864cd
+SHA512:
+  metadata.gz: 09ecda38f19e15ba0c4bc2efc97b4d12482d0185fe990035edc8c267f2ad6f2485fd1c90effae3fcd47ea0b3fd3422e5f76e290f56314904554831224e387044
+  data.tar.gz: 3a859cdd4ee599e02b2f8bf3c6f3a3899baed76bbce4961e3390cc2f7dfab1c8f3fcf16fe0e606c152f2de69c32bb5e834c4981b87407e611e1a9b309b07d218

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+Makefile
+mqueue.so
+mqueue.o
+mkmf.log
+mqueue.bundle

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 2.1.8
+before_install: gem install bundler -v 1.11.2
+script: bundle exec rake compile

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mqueue.gemspec
+gemspec
+gem 'pry-nav', group: [:development, :test]
+gem 'bundler', group: [:development, :test]
+gem 'minitest', group: [:development, :test]
+gem 'rake-compiler', group: [:development, :test]

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Irfan Sharif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,111 @@
+# GEM: mqueue ![](https://travis-ci.org/irfansharif/mqueue.svg?branch=master)
+
+Lightweight wrapper built around [POSIX message queues](http://man7.org/linux/man-pages/man7/mq_overview.7.html). Abstracted functionality when designing a module for Ruby IPC with concurrent processes, reference used was [The Linux Programming Interface](http://man7.org/tlpi/download/TLPI-52-POSIX_Message_Queues.pdf).
+
+Highlighted features:
+
+* POSIX messages have associated priorities, messages are always strictly queued (and received) in priority order
+* POSIX message queues have associated sets of attributes that can be set when the queue is created or opened
+* Allows a process to register for message notification
+from a queue. After registering, the process is notified of the availability of a message
+by delivery of a signal or by the invocation of a function in a separate thread
+* Ridiculously fast, everything is delegated to the kernel
+*
+
+**NOTE:** At the time of writing there already existed a [wrapper](https://github.com/Sirupsen/posix-mqueue) around POSIX message queues but didn't offer some of the notification subscription functionality I needed for IPC, while I could've opted to add that into the original (you'll notice a lot of overlap), I wanted to experiment with C extensions in ruby for some other libraries I'm going to be working on in the future, messaging queues was a subject I was sufficiently versed it to start with.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mqueue'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mqueue
+
+## Usage
+
+```ruby
+require 'mqueue'
+
+# Queue names must start with '/', shown below are the default settings
+provided # by the Kernel (except for queue_name), check below for options
+available for flags and how to change # default settings outside ruby
+mq = MQueue.new("/queue_name", capacity: 10, max_msgsize: 8192, flags: [:creat, :rdwr])
+mq.send "message"
+
+mq.receive
+# => "message"
+
+fork { mq.send "another one" }
+
+# Blocks on empty queues, in this case until forked process adds message onto queue
+mq.recieve
+# => "another one"
+
+10.times do
+  mq.send "42"
+end
+
+mq.size
+# => 10
+
+# Timed send takes an optional parameter indicating duration it would wait
+# (in seconds) before returning false, defaults to 0
+refute mq.timedsend "queue full, this will fail", 0
+
+mq.full?
+# => true
+
+# This would block indefinitely until something is removed from the queue
+# mq.send "the answer to life"
+
+# Empties queue of all messages, includes pending messages
+mq.flush
+
+# Timed receive takes an optional parameter indicating duration it would wait
+# (in seconds) before returning false, defaults to 0
+refute mq.timedreceive "queue empty, this will fail too", 0
+
+mq.empty?
+# => true
+
+# Notification as defined here is when a message is added to previously empty
+# queue, will not get triggered if someone else is waiting on `receive` or
+# messages added to non-empty queues. is triggered asynchronously, only one
+# process will be able to add the notification hook to a particular queue (NOT IMPLEMENTED)
+mq.on_notification do |msg|
+  puts "#{msg} delivered through notification hook"
+end
+
+mq.send "notification"
+# => "notification delivered through notification hook"
+
+# Hook no longer triggered (NOT IMPLEMENTED)
+mq.disable_notification
+mq.send "ignored notification"
+
+# Deletes the queue and any containing messages, if not done so it persists until system reboot
+mq.delete
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [irfansharif](https://github.com/irfansharif/mqueue).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,15 @@
+require "bundler/gem_tasks"
+require "rake/extensiontask"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+Rake::ExtensionTask.new "mqueue" do |ext|
+  ext.lib_dir = "lib/mqueue"
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "mqueue"
+require "pry"
+
+mq = MQueue.new "/queue_name", flags: [:creat, :rdwr]
+
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/ext/mqueue/extconf.rb

@@ -0,0 +1,9 @@
+# Extension configuration
+require 'mkmf'
+
+have_header('mqueue.h')
+have_library('rt')
+
+extension_name = 'mqueue'
+dir_config(extension_name)
+create_makefile(extension_name)

data/ext/mqueue/mq.h

@@ -0,0 +1,46 @@
+#ifndef MQUEUE
+#define MQUEUE
+
+#include <ruby.h>
+#include <fcntl.h>      /* Defines O_* constants */
+#include <sys/stat.h>   /* Defines mode constants */
+#include <mqueue.h>
+#include <unistd.h>
+#include <time.h>
+#include <pthread.h>
+
+typedef struct {
+  mqd_t queue_descriptor;
+  struct mq_attr attributes;
+  char* queue_name;
+} mqueue_t;
+
+static void free_mqueue(void*);
+size_t size_mqueue(const void*);
+long generate_flags(VALUE);
+static void notification_function(union sigval);
+
+static const rb_data_type_t
+mqueue_data_type = {
+  "mqueue_data_type",
+  {
+    0,
+    free_mqueue,
+    size_mqueue
+  }
+};
+
+void Init_mqueue();
+static VALUE alloc_mqueue(VALUE);
+VALUE  mqueue_initialize(int, VALUE*, VALUE);
+
+VALUE mqueue_send(VALUE, VALUE);
+VALUE mqueue_receive(VALUE);
+VALUE mqueue_timedsend(int, VALUE*, VALUE);
+VALUE mqueue_timedreceive(int, VALUE*, VALUE);
+VALUE mqueue_size(VALUE);
+VALUE mqueue_capacity(VALUE);
+VALUE mqueue_max_msgsize(VALUE);
+VALUE mqueue_delete(VALUE);
+
+#endif

data/ext/mqueue/mqueue.c

@@ -0,0 +1,245 @@
+#include "mq.h"
+
+void
+Init_mqueue() {
+  VALUE mqueue = rb_define_class("MQueue", rb_cObject);
+  rb_define_alloc_func(mqueue, alloc_mqueue);
+
+  rb_define_method(mqueue, "initialize", mqueue_initialize, -1);
+  rb_define_method(mqueue, "send", mqueue_send, 1);
+  rb_define_method(mqueue, "receive", mqueue_receive, 0);
+  rb_define_method(mqueue, "timedsend", mqueue_timedsend, -1);
+  rb_define_method(mqueue, "timedreceive", mqueue_timedreceive, -1);
+  rb_define_method(mqueue, "size", mqueue_size, 0);
+  rb_define_method(mqueue, "capacity", mqueue_capacity, 0);
+  rb_define_method(mqueue, "max_msgsize", mqueue_max_msgsize, 0);
+  rb_define_method(mqueue, "delete", mqueue_delete, 0);
+}
+
+static VALUE
+alloc_mqueue(VALUE klass) {
+  mqueue_t* queue_ptr;
+  VALUE object = TypedData_Make_Struct(klass, mqueue_t, &mqueue_data_type, queue_ptr);
+
+  (*queue_ptr).queue_descriptor = -1;
+  (*queue_ptr).queue_name = NULL;
+  (*queue_ptr).attributes.mq_curmsgs = 0;
+  (*queue_ptr).attributes.mq_flags = 0;
+
+  return object;
+}
+
+VALUE
+mqueue_initialize(int argc, VALUE* argv, VALUE self) {
+  VALUE queue_name, options;
+  mqueue_t* queue_ptr;
+
+  rb_scan_args(argc, argv, "1:", &queue_name, &options);
+  TypedData_Get_Struct(self, mqueue_t, &mqueue_data_type, queue_ptr);
+
+  if ((*queue_ptr).queue_descriptor != -1)
+    rb_raise(rb_eRuntimeError, "Illegal initialization");
+
+  if (TYPE(queue_name) != T_STRING)
+    rb_raise(rb_eTypeError, "Invalid queue name, must be a string");
+  if (TYPE(options) != T_HASH)
+    options = rb_hash_new();
+
+  (*queue_ptr).queue_name = ruby_strdup(StringValueCStr(queue_name));
+  (*queue_ptr).attributes.mq_maxmsg = FIX2INT(rb_hash_lookup2(options,
+        ID2SYM(rb_intern("capacity")),
+        INT2NUM(10))
+      );
+  (*queue_ptr).attributes.mq_msgsize = FIX2INT(rb_hash_lookup2(options,
+        ID2SYM(rb_intern("max_msgsize")),
+        INT2NUM(4096))
+      );
+  (*queue_ptr).attributes.mq_flags = generate_flags(options);
+  (*queue_ptr).queue_descriptor = mq_open((*queue_ptr).queue_name,
+        (*queue_ptr).attributes.mq_flags,
+        S_IRUSR | S_IWUSR,
+        &(*queue_ptr).attributes
+      );
+
+  if ((*queue_ptr).queue_descriptor == (mqd_t)-1)
+    rb_raise(rb_eRuntimeError, "Unable to initialize");
+
+  return self;
+}
+
+VALUE
+mqueue_delete(VALUE self) {
+  mqueue_t* queue_ptr;
+  TypedData_Get_Struct(self, mqueue_t, &mqueue_data_type, queue_ptr);
+
+  if (mq_unlink((*queue_ptr).queue_name) == -1)
+    return Qfalse;
+
+  return Qtrue;
+}
+
+VALUE
+mqueue_send(VALUE self, VALUE message) {
+  mqueue_t* queue_ptr;
+  char* msg_ptr;
+  size_t msg_len;
+
+  TypedData_Get_Struct(self, mqueue_t, &mqueue_data_type, queue_ptr);
+
+  msg_ptr = RSTRING_PTR(message);
+  msg_len = RSTRING_LEN(message);
+
+  if (mq_send((*queue_ptr).queue_descriptor, msg_ptr, msg_len, 0) == -1)
+    return Qfalse;
+  return Qtrue;
+}
+
+VALUE
+mqueue_receive(VALUE self) {
+  mqueue_t* queue_ptr;
+  int len;
+
+  TypedData_Get_Struct(self, mqueue_t, &mqueue_data_type, queue_ptr);
+  char msg_buffer[(*queue_ptr).attributes.mq_msgsize];
+
+  if ((len = mq_receive((*queue_ptr).queue_descriptor, msg_buffer, (*queue_ptr).attributes.mq_msgsize, 0)) == -1)
+    return Qfalse;
+
+  return rb_str_new(msg_buffer, len);
+}
+
+VALUE
+mqueue_timedsend(int argc, VALUE* argv, VALUE self) {
+  VALUE message, timeout;
+  mqueue_t* queue_ptr;
+  char* msg_ptr;
+  size_t msg_len;
+  struct timespec abs_timeout;
+
+  rb_scan_args(argc, argv, "11", &message, &timeout);
+
+  if (NIL_P(timeout))
+    timeout = INT2NUM(10);
+
+  TypedData_Get_Struct(self, mqueue_t, &mqueue_data_type, queue_ptr);
+
+  msg_ptr = RSTRING_PTR(message);
+  msg_len = RSTRING_LEN(message);
+
+  if (clock_gettime(CLOCK_REALTIME, &abs_timeout) == -1)
+    return Qfalse;
+
+  abs_timeout.tv_sec += NUM2INT(timeout);
+
+  if (mq_timedsend((*queue_ptr).queue_descriptor, msg_ptr, msg_len, 0, &abs_timeout) == -1)
+    return Qfalse;
+  return Qtrue;
+}
+
+VALUE
+mqueue_timedreceive(int argc, VALUE* argv, VALUE self) {
+  VALUE timeout;
+  mqueue_t* queue_ptr;
+  struct timespec abs_timeout;
+
+  rb_scan_args(argc, argv, "01", &timeout);
+
+  if (NIL_P(timeout))
+    timeout = INT2NUM(10);
+
+  TypedData_Get_Struct(self, mqueue_t, &mqueue_data_type, queue_ptr);
+  char msg_buffer[(*queue_ptr).attributes.mq_msgsize];
+
+  if (clock_gettime(CLOCK_REALTIME, &abs_timeout) == -1)
+    return Qfalse;
+
+  abs_timeout.tv_sec += NUM2INT(timeout);
+  if (mq_timedreceive((*queue_ptr).queue_descriptor, msg_buffer, (*queue_ptr).attributes.mq_msgsize, 0, &abs_timeout) == -1)
+    return Qfalse;
+
+  return rb_str_new_cstr(msg_buffer);
+}
+
+VALUE
+mqueue_size(VALUE self) {
+  mqueue_t* queue_ptr;
+  struct mq_attr attributes;
+
+  TypedData_Get_Struct(self, mqueue_t, &mqueue_data_type, queue_ptr);
+
+  if (mq_getattr((*queue_ptr).queue_descriptor, &attributes) == -1)
+    return INT2NUM(-1);
+
+  return INT2NUM(attributes.mq_curmsgs);
+}
+
+VALUE
+mqueue_capacity(VALUE self) {
+  mqueue_t* queue_ptr;
+  struct mq_attr attributes;
+
+  TypedData_Get_Struct(self, mqueue_t, &mqueue_data_type, queue_ptr);
+
+  if (mq_getattr((*queue_ptr).queue_descriptor, &attributes) == -1)
+    return INT2NUM(-1);
+
+  return INT2NUM(attributes.mq_maxmsg);
+}
+
+VALUE
+mqueue_max_msgsize(VALUE self) {
+  mqueue_t* queue_ptr;
+  struct mq_attr attributes;
+
+  TypedData_Get_Struct(self, mqueue_t, &mqueue_data_type, queue_ptr);
+
+  if (mq_getattr((*queue_ptr).queue_descriptor, &attributes) == -1)
+    return INT2NUM(-1);
+
+  return INT2NUM(attributes.mq_msgsize);
+}
+
+/******************************************************************************/
+
+static void
+free_mqueue (void* ptr) {
+  mqueue_t* queue_ptr = ptr;
+  if (mq_close((*queue_ptr).queue_descriptor) == -1)
+    rb_sys_fail("mq_close failed");
+
+  free((*queue_ptr).queue_name);
+  free(ptr);
+}
+
+size_t
+size_mqueue (const void* ptr) {
+  mqueue_t* queue_ptr = queue_ptr;
+  return sizeof(mqueue_t) + sizeof(char) * strlen((*queue_ptr).queue_name);
+}
+
+long
+generate_flags(VALUE options) {
+  VALUE flags = rb_hash_lookup(options, ID2SYM(rb_intern("flags"))), cur_flag;
+  if (flags == Qnil || RARRAY_LEN(flags) == 0)
+    return 0;
+  int num_flags = RARRAY_LEN(flags), i;
+  long mq_flags = 0;
+
+  for(i = 0; i < num_flags; i++) {
+    cur_flag = rb_ary_entry(flags, i);
+    if (cur_flag == ID2SYM(rb_intern("creat")))
+      mq_flags |= O_CREAT;
+    else if (cur_flag ==  ID2SYM(rb_intern("excl")))
+      mq_flags |= O_EXCL;
+    else if (cur_flag == ID2SYM(rb_intern("rdonly")))
+      mq_flags |= O_RDONLY;
+    else if (cur_flag == ID2SYM(rb_intern("wronly")))
+      mq_flags |= O_WRONLY;
+    else if (cur_flag == ID2SYM(rb_intern("rdwr")))
+      mq_flags |= O_RDWR;
+    else if (cur_flag == ID2SYM(rb_intern("nonblock")))
+      mq_flags |= O_NONBLOCK;
+  }
+
+  return mq_flags;
+}

data/lib/mqueue.rb

@@ -0,0 +1,21 @@
+require "mqueue/mqueue"
+
+module MQueueExtensions
+  def flush
+    values = []
+    values << timedreceive(0) while size > 0
+    values
+  end
+
+  def full?
+    size == capacity
+  end
+
+  def empty?
+    size == 0
+  end
+end
+
+class MQueue
+  prepend MQueueExtensions
+end

data/lib/mqueue/version.rb

@@ -0,0 +1,3 @@
+class MQueue
+  VERSION = "0.1.0"
+end

data/mqueue.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mqueue/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mqueue"
+  spec.version       = MQueue::VERSION
+  spec.authors       = ["Irfan Sharif"]
+  spec.email         = ["irfanmahmoudsharif@gmail.com"]
+
+  spec.summary       = %q{Ruby wrapper around POSIX IPC message queue}
+  spec.description   = %q{Lightweight wrapper built around POSIX message queues.
+                          Reference used was The Linux Programming Interface.}
+  spec.homepage      = "https://github.com/irfansharif/mqueue"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.extensions = %w[ext/mqueue/extconf.rb]
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: mqueue
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Irfan Sharif
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-05-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: |-
+  Lightweight wrapper built around POSIX message queues.
+                            Reference used was The Linux Programming Interface.
+email:
+- irfanmahmoudsharif@gmail.com
+executables: []
+extensions:
+- ext/mqueue/extconf.rb
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- ext/mqueue/extconf.rb
+- ext/mqueue/mq.h
+- ext/mqueue/mqueue.c
+- lib/mqueue.rb
+- lib/mqueue/version.rb
+- mqueue.gemspec
+homepage: https://github.com/irfansharif/mqueue
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.2
+signing_key: 
+specification_version: 4
+summary: Ruby wrapper around POSIX IPC message queue
+test_files: []