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.8, Ruby 1.9 and Rubinius 1.2
  30
  31 * Documented library API
  32
  33 * Includes a generic "posix-mq-rb" command-line tool with manpage.
  34
  35 == Install
  36
  37 Operating system support (or library emulation) for POSIX message queues
  38 is required.  Most modern GNU/Linux distributions support this
  39 out-of-the-box.
  40
  41 If you're using a packaged Ruby distribution, make sure you have a C
  42 compiler and the matching Ruby development libraries and headers.
  43
  44 If you plan on using the command-line client, a tarball installation
  45 starts up faster and is recommended.  Just grab the tarball from:
  46
  47 http://bogomips.org/ruby_posix_mq/files/
  48 Unpack it, and run "ruby setup.rb"
  49
  50 Otherwise, via RubyGems: gem install posix_mq
  51
  52 == Usage
  53
  54 The Linux mq_overview(7)
  55 {manpage}[http://kernel.org/doc/man-pages/online/pages/man7/mq_overview.7.html]
  56 provides a good overview of programming with POSIX message queues.
  57
  58 Under FreeBSD, you must load the
  59 {mqueuefs(5)}[http://freebsd.org/cgi/man.cgi?query=mqueuefs]
  60 kernel module before attempting to use POSIX message queues:
  61
  62     kldload mqueuefs
  63
  64 Our API matches the C api closely, see the RDoc for full API
  65 documentation.  Here is an example of a process communicating
  66 with itself.  In practice, processes that send will be different
  67 from processes that receive.
  68
  69     require 'posix_mq'
  70     mq = POSIX_MQ.new("/foo", :rw)
  71
  72     # hello world
  73     mq << "hello world"
  74     puts mq.receive.first # => should print "hello world"
  75
  76     # non-blocking operation
  77     mq.nonblock = true
  78     begin
  79       mq.receive
  80     rescue Errno::EAGAIN
  81     end
  82
  83     trap(:USR1) { puts mq.receive.first }
  84     mq.notify = :USR1
  85     mq.send "fire USR1 handler"
  86     # "fire USR1 handler" should be printed now
  87
  88 == Development
  89
  90 You can get the latest source via git from the following locations:
  91
  92   git://bogomips.org/ruby_posix_mq.git
  93   git://repo.or.cz/ruby_posix_mq.git (mirror)
  94
  95 You may browse the code from the web and download the latest snapshot
  96 tarballs here:
  97
  98 * http://bogomips.org/ruby_posix_mq.git (cgit)
  99 * http://repo.or.cz/w/ruby_posix_mq.git (gitweb)
 100
 101 Inline patches (from "git format-patch") to the mailing list are
 102 preferred because they allow code review and comments in the reply to
 103 the patch.
 104
 105 We will adhere to mostly the same conventions for patch submissions as
 106 git itself.  See the Documentation/SubmittingPatches document
 107 distributed with git on on patch submission guidelines to follow.  Just
 108 don't email the git mailing list or maintainer with posix_mq patches.
 109
 110 == Contact
 111
 112 All feedback (bug reports, user/development discussion, patches, pull
 113 requests) go to the mailing list: mailto:ruby.posix.mq@librelist.com
 114
 115 == Mailing List Archives
 116
 117 In addition to the rsync-able archives provided by http://librelist.com/, we
 118 are also mirrored to
 119 {Gmane}[http://gmane.org/info.php?group=gmane.comp.lang.ruby.posix-mq.general]
 120 and maintain our own mbox mirrors downloadable via HTTP.
 121
 122 * nntp://news.gmane.org/gmane.comp.lang.ruby.posix-mq.general
 123 * http://bogomips.org/ruby_posix_mq/archives/