1 = posix_mq - POSIX Message Queues for Ruby
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.
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.
14 * Supports message notifications via signals on all platforms
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.
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.
24 * Optional timeouts may be applied to send and receive operations.
26 * Thread-safe blocking operations under Ruby 1.9, releases GVL
27 before blocking operations.
29 * Works under Ruby 1.8, Ruby 1.9 and Rubinius 1.2
31 * Documented library API
33 * Includes a generic "posix-mq-rb" command-line tool with manpage.
37 Operating system support (or library emulation) for POSIX message queues
38 is required. Most modern GNU/Linux distributions support this
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.
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:
47 http://bogomips.org/ruby_posix_mq/files/
48 Unpack it, and run "ruby setup.rb"
50 Otherwise, via RubyGems: gem install posix_mq
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.
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:
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.
70 mq = POSIX_MQ.new("/foo", :rw)
74 puts mq.receive.first # => should print "hello world"
76 # non-blocking operation
83 trap(:USR1) { puts mq.receive.first }
85 mq.send "fire USR1 handler"
86 # "fire USR1 handler" should be printed now
90 You can get the latest source via git from the following locations:
92 git://git.bogomips.org/ruby_posix_mq.git
93 git://repo.or.cz/ruby_posix_mq.git (mirror)
95 You may browse the code from the web and download the latest snapshot
98 * http://git.bogomips.org/cgit/ruby_posix_mq.git (cgit)
99 * http://repo.or.cz/w/ruby_posix_mq.git (gitweb)
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
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.
112 All feedback (bug reports, user/development discussion, patches, pull
113 requests) go to the mailing list: mailto:ruby.posix.mq@librelist.com
115 == Mailing List Archives
117 In addition to the rsync-able archives provided by http://librelist.com/, we
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.
122 * nntp://news.gmane.org/gmane.comp.lang.ruby.posix-mq.general
123 * http://bogomips.org/ruby_posix_mq/archives/