fix compiler warnings, oops
[ruby_posix_mq.git] / README
blob9d83f1d9e36d239f89520f6e237e1bd53ad1a4d2
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.
12 == Features
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.
35 * {EventMachine}[http://rubyeventmachine.com/] integration via
36   {em-posixmq}[https://github.com/ibc/em-posixmq]
38 == Install
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.
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.
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:
50 http://bogomips.org/ruby_posix_mq/files/
51 Unpack it, and run "ruby setup.rb"
53 Otherwise, via RubyGems: gem install posix_mq
55 == Usage
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.
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:
65     kldload mqueuefs
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.
72     require 'posix_mq'
73     mq = POSIX_MQ.new("/foo", :rw)
75     # hello world
76     mq << "hello world"
77     puts mq.receive.first # => should print "hello world"
79     # non-blocking operation
80     mq.nonblock = true
81     begin
82       mq.receive
83     rescue Errno::EAGAIN
84     end
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
91 == Development
93 You can get the latest source via git from the following locations:
95   git://bogomips.org/ruby_posix_mq.git
96   git://repo.or.cz/ruby_posix_mq.git (mirror)
98 You may browse the code from the web and download the latest snapshot
99 tarballs here:
101 * http://bogomips.org/ruby_posix_mq.git (cgit)
102 * http://repo.or.cz/w/ruby_posix_mq.git (gitweb)
104 Inline patches (from "git format-patch") to the mailing list are
105 preferred because they allow code review and comments in the reply to
106 the patch.
108 We will adhere to mostly the same conventions for patch submissions as
109 git itself.  See the Documentation/SubmittingPatches document
110 distributed with git on on patch submission guidelines to follow.  Just
111 don't email the git mailing list or maintainer with Ruby posix_mq patches.
113 == Contact
115 All feedback (bug reports, user/development discussion, patches, pull
116 requests) go to the mailing list: mailto:ruby.posix.mq@librelist.com
118 Send patches (from "git format-patch") with "git send-email" and do not
119 send HTML email or attachments.  We are very responsive to email and you
120 will usually get a response within 24-72 hours.
122 == Mailing List Archives
124 In addition to the rsync-able archives provided by http://librelist.com/, we
125 are also mirrored to
126 {Gmane}[http://gmane.org/info.php?group=gmane.comp.lang.ruby.posix-mq.general]
127 and maintain our own mbox mirrors downloadable via HTTP.
129 * nntp://news.gmane.org/gmane.comp.lang.ruby.posix-mq.general
130 * http://bogomips.org/ruby_posix_mq/archives/