README

   1 = posix_mq - POSIX message queues for Ruby
   2
   3 POSIX message queues allow local processes to exchange data in the form
   4 of messages.  This API is distinct from that provided by System V
   5 message queues, but provides similar functionality.
   6
   7 POSIX message queues may be implemented in the kernel for fast,
   8 low-latency communication between processes on the same machine.
   9 POSIX message queues are not intended to replace userspace,
  10 network-aware message queue implementations.
  11
  12 == Features
  13
  14 * Supports message notifications via signals on all platforms
  15
  16 * Supports portable non-blocking operation.  Under Linux 2.6.6+ and
  17   FreeBSD 7.2+, POSIX_MQ objects may even be used with event
  18   notification mechanisms such as IO.select.
  19
  20 * Supports notifications via block execution in a separate thread
  21   on platforms that implement SIGEV_THREAD for mq_notify(3),
  22   currently only GNU/Linux.
  23
  24 * Optional timeouts may be applied to send and receive operations.
  25
  26 * Thread-safe blocking operations under Ruby 1.9+, releases GVL
  27   before blocking operations.
  28
  29 * Works under Ruby 1.9 and later.
  30
  31 * Documented library API
  32
  33 * Includes a generic "posix-mq-rb" command-line tool with manpage.
  34
  35 * {EventMachine}[http://rubyeventmachine.com/] integration via
  36   {em-posixmq}[https://github.com/ibc/em-posixmq]
  37
  38 == Install
  39
  40 Operating system support (or library emulation) for POSIX message queues
  41 is required.  Most modern GNU/Linux distributions support this
  42 out-of-the-box.
  43
  44 If you're using a packaged Ruby distribution, make sure you have a C
  45 compiler and the matching Ruby development libraries and headers.
  46
  47 If you plan on using the command-line client, a tarball installation
  48 starts up faster and is recommended.  Just grab the tarball from:
  49
  50 https://bogomips.org/ruby_posix_mq/files/
  51 Unpack it, and run "ruby setup.rb"
  52
  53 Otherwise, via RubyGems: gem install posix_mq
  54
  55 == Usage
  56
  57 The Linux mq_overview(7)
  58 {manpage}[http://kernel.org/doc/man-pages/online/pages/man7/mq_overview.7.html]
  59 provides a good overview of programming with POSIX message queues.
  60
  61 Under FreeBSD, you must load the
  62 {mqueuefs(5)}[http://freebsd.org/cgi/man.cgi?query=mqueuefs]
  63 kernel module before attempting to use POSIX message queues:
  64
  65     kldload mqueuefs
  66
  67 Our API matches the POSIX C API closely, see the RDoc for full API
  68 documentation.  Here is an example of a process communicating
  69 with itself.  In practice, processes that send will be different
  70 from processes that receive.
  71
  72     require 'posix_mq'
  73     mq = POSIX_MQ.new("/foo", :rw)
  74
  75     # hello world
  76     mq << "hello world"
  77     puts mq.receive.first # => should print "hello world"
  78
  79     # non-blocking operation
  80     mq.nonblock = true
  81     begin
  82       mq.receive
  83     rescue Errno::EAGAIN
  84     end
  85
  86     trap(:USR1) { puts mq.receive.first }
  87     mq.notify = :USR1
  88     mq.send "fire USR1 handler"
  89     # "fire USR1 handler" should be printed now
  90
  91 == Development
  92
  93 You can get the latest source via git from the following locations:
  94
  95         git://bogomips.org/ruby_posix_mq.git
  96         git://repo.or.cz/ruby_posix_mq.git (mirror)
  97
  98 You may also browse the code from the web:
  99
 100 * https://bogomips.org/ruby_posix_mq.git
 101 * http://repo.or.cz/w/ruby_posix_mq.git (gitweb)
 102
 103 Inline patches (from "git format-patch") to the mailing list are
 104 preferred because they allow code review and comments in the reply to
 105 the patch.
 106
 107 We will adhere to mostly the same conventions for patch submissions as
 108 git itself.  See the Documentation/SubmittingPatches document
 109 distributed with git on patch submission guidelines to follow:
 110
 111 https://git.kernel.org/cgit/git/git.git/plain/Documentation/SubmittingPatches
 112
 113 Just don't mail the git list or maintainer with Ruby posix_mq patches.
 114
 115 == Contact
 116
 117 All feedback (bug reports, user/development discussion, patches, pull
 118 requests) go to the mailing list: mailto:ruby-posix-mq@bogomips.org
 119
 120 Send patches (from "git format-patch") with "git send-email" and do not
 121 send HTML email or attachments.  We are very responsive to email and you
 122 will usually get a response within 24-72 hours.
 123
 124 Subscription is optional: mailto:ruby-posix-mq+subscribe@bogomips.org
 125
 126 Read-only mail archives are available over HTTPS and NNTP:
 127
 128   https://bogomips.org/ruby-posix-mq/
 129   nntp://news.public-inbox.org/inbox.comp.lang.ruby.posix-mq