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.
  15
  16 * Supports portable non-blocking operation.  Under Linux 2.6.6+ only,
  17   POSIX_MQ objects may even be used with event notification mechanisms
  18   such as IO.select.
  19
  20 * Optional timeouts may be applied to send and receive operations.
  21
  22 * Thread-safe under Ruby 1.9, releases GVL before blocking operations.
  23
  24 * Documented library API
  25
  26 * Includes a generic "posix-mq.rb" command-line tool with manpage.
  27
  28 == Install
  29
  30 Operating system support (or library emulation) for POSIX message queues
  31 is required.  Most modern GNU/Linux distributions support this
  32 out-of-the-box.
  33
  34 If you're using a packaged Ruby distribution, make sure you have a C
  35 compiler and the matching Ruby development libraries and headers.
  36
  37 If you plan on using the command-line client, a tarball installation
  38 starts up faster and is recommended.  Just grab the tarball from:
  39
  40 http://bogomips.org/ruby_posix_mq/files/
  41 Unpack it, and run "ruby setup.rb"
  42
  43 Otherwise, via RubyGems: gem install posix_mq
  44
  45 == Usage
  46
  47 The Linux mq_overview(7)
  48 {manpage}[http://kernel.org/doc/man-pages/online/pages/man7/mq_overview.7.html]
  49 provides a good overview of programming with POSIX message queues.
  50
  51 Under FreeBSD, you must load the
  52 {mqueuefs(5)}[http://freebsd.org/cgi/man.cgi?query=mqueuefs]
  53 kernel module before attempting to use POSIX message queues:
  54
  55     kldload mqueuefs
  56
  57 Our API matches the C api closely, see the RDoc for full API
  58 documentation.  Here is an example of a process communicating
  59 with itself.  In practice, processes that send will be different
  60 from processes that receive.
  61
  62     require 'posix_mq'
  63     mq = POSIX_MQ.new("/foo", :rw)
  64
  65     # hello world
  66     mq << "hello world"
  67     puts mq.receive.first # => should print "hello world"
  68
  69     # non-blocking operation
  70     mq.nonblock = true
  71     begin
  72       mq.receive
  73     rescue Errno::EAGAIN
  74     end
  75
  76     trap(:USR1) { puts mq.receive.first }
  77     mq.notify = :USR1
  78     mq.send "fire USR1 handler"
  79     # "fire USR1 handler" should be printed now
  80
  81 == Development
  82
  83 You can get the latest source via git from the following locations:
  84
  85   git://git.bogomips.org/ruby_posix_mq.git
  86   git://repo.or.cz/ruby_posix_mq.git (mirror)
  87
  88 You may browse the code from the web and download the latest snapshot
  89 tarballs here:
  90
  91 * http://git.bogomips.org/cgit/ruby_posix_mq.git (cgit)
  92 * http://repo.or.cz/w/ruby_posix_mq.git (gitweb)
  93
  94 Inline patches (from "git format-patch") to the mailing list are
  95 preferred because they allow code review and comments in the reply to
  96 the patch.
  97
  98 We will adhere to mostly the same conventions for patch submissions as
  99 git itself.  See the Documentation/SubmittingPatches document
 100 distributed with git on on patch submission guidelines to follow.  Just
 101 don't email the git mailing list or maintainer with posix_mq patches.
 102
 103 == Contact
 104
 105 All feedback (bug reports, user/development discussion, patches, pull
 106 requests) go to the mailing list: mailto:ruby.posix.mq@librelist.com