Struct posixmq::PosixMq

pub struct PosixMq { /* fields omitted */ }

A descriptor for an open posix message queue.

Message queues can be sent to and / or received from depending on the options it was opened with.

The descriptor is closed when this struct is dropped.

See the documentation in the crate root for examples, portability notes and OS details.

Implementations

impl PosixMq

pub fn open<N: AsRef<[u8]> + ?Sized>(name: &N) -> Result<Self, Error>

Open an existing message queue in read-write mode.

See OpenOptions::open() for details and possible errors.

pub fn create<N: AsRef<[u8]> + ?Sized>(name: &N) -> Result<Self, Error>

Open a message queue in read-write mode, creating it if it doesn't exists.

See OpenOptions::open() for details and possible errors.

pub fn send(&self, priority: u32, msg: &[u8]) -> Result<(), Error>

Add a message to the queue.

For maximum portability, avoid using priorities >= 32 or sending zero-length messages.

Errors

• Queue is full and opened in nonblocking mode (EAGAIN) => ErrorKind::WouldBlock
• Message is too big for the queue (EMSGSIZE) => ErrorKind::Other
• Message is zero-length and the OS doesn't allow this (EMSGSIZE) => ErrorKind::Other
• Priority is too high (EINVAL) => ErrorKind::InvalidInput
• Queue is opened in read-only mode (EBADF) => ErrorKind::Other
• Possibly other => ErrorKind::Other

pub fn recv(&self, msgbuf: &mut [u8]) -> Result<(u32, usize), Error>

Take the message with the highest priority from the queue.

The buffer must be at least as big as the maximum message length.

Errors

• Queue is empty and opened in nonblocking mode (EAGAIN) => ErrorKind::WouldBlock
• The receive buffer is smaller than the queue's maximum message size (EMSGSIZE) => ErrorKind::Other
• Queue is opened in write-only mode (EBADF) => ErrorKind::Other
• Possibly other => ErrorKind::Other

pub fn iter<'a>(&'a self) -> Iter<'a>

Returns an Iterator which calls recv() repeatedly with an appropriately sized buffer.

If the message queue is opened in non-blocking mode the iterator can be used to drain the queue. Otherwise it will block and never end.

pub fn send_timeout(
    &self,
    priority: u32,
    msg: &[u8],
    timeout: Duration
) -> Result<(), Error>

Add a message to the queue or cancel if it's still full after a given duration.

Returns immediately if opened in nonblocking mode, and the timeout has no effect.

For maximum portability, avoid using priorities >= 32 or sending zero-length messages.

Errors

• Timeout expired (ETIMEDOUT) => ErrorKind::TimedOut
• Message is too big for the queue (EMSGSIZE) => ErrorKind::Other
• OS doesn't allow empty messages (EMSGSIZE) => ErrorKind::Other
• Priority is too high (EINVAL) => ErrorKind::InvalidInput
• Queue is full and opened in nonblocking mode (EAGAIN) => ErrorKind::WouldBlock
• Queue is opened in write-only mode (EBADF) => ErrorKind::Other
• Timeout is too long / not representable => ErrorKind::InvalidInput
• Possibly other => ErrorKind::Other

pub fn send_deadline(
    &self,
    priority: u32,
    msg: &[u8],
    deadline: SystemTime
) -> Result<(), Error>

Add a message to the queue or cancel if the queue is still full at a certain point in time.

Returns immediately if opened in nonblocking mode, and the timeout has no effect.
The deadline is a SystemTime because the queues are intended for inter-process commonication, and Instant might be process-specific.

For maximum portability, avoid using priorities >= 32 or sending zero-length messages.

Errors

• Deadline reached (ETIMEDOUT) => ErrorKind::TimedOut
• Message is too big for the queue (EMSGSIZE) => ErrorKind::Other
• OS doesn't allow empty messages (EMSGSIZE) => ErrorKind::Other
• Priority is too high (EINVAL) => ErrorKind::InvalidInput
• Queue is full and opened in nonblocking mode (EAGAIN) => ErrorKind::WouldBlock
• Queue is opened in write-only mode (EBADF) => ErrorKind::Other
• Possibly other => ErrorKind::Other

pub fn recv_timeout(
    &self,
    msgbuf: &mut [u8],
    timeout: Duration
) -> Result<(u32, usize), Error>

Take the message with the highest priority from the queue or cancel if the queue still empty after a given duration.

Returns immediately if opened in nonblocking mode, and the timeout has no effect.

Errors

• Timeout expired (ETIMEDOUT) => ErrorKind::TimedOut
• The receive buffer is smaller than the queue's maximum message size (EMSGSIZE) => ErrorKind::Other
• Queue is empty and opened in nonblocking mode (EAGAIN) => ErrorKind::WouldBlock
• Queue is opened in read-only mode (EBADF) => ErrorKind::Other
• Timeout is too long / not representable => ErrorKind::InvalidInput
• Possibly other => ErrorKind::Other

pub fn recv_deadline(
    &self,
    msgbuf: &mut [u8],
    deadline: SystemTime
) -> Result<(u32, usize), Error>

Take the message with the highest priority from the queue or cancel if the queue is still empty at a point in time.

Returns immediately if opened in nonblocking mode, and the timeout has no effect.
The deadline is a SystemTime because the queues are intended for inter-process commonication, and Instant might be process-specific.

Errors

• Deadline reached (ETIMEDOUT) => ErrorKind::TimedOut
• The receive buffer is smaller than the queue's maximum message size (EMSGSIZE) => ErrorKind::Other
• Queue is empty and opened in nonblocking mode (EAGAIN) => ErrorKind::WouldBlock
• Queue is opened in read-only mode (EBADF) => ErrorKind::Other
• Possibly other => ErrorKind::Other

pub fn attributes(&self) -> Result<Attributes, Error>

Get information about the state of the message queue.

Errors

Retrieving these attributes should only fail if the underlying descriptor has been closed or is not a message queue.

On operating systems where the descriptor is a pointer, such as on FreeBSD and Illumos, such bugs will enable undefined behavior and this call will dereference freed or uninitialized memory.
(That doesn't make this function unsafe though - PosixMq::from_raw_mqd() and mq_close() are.)

While a send() or recv() ran in place of this call would also have failed immediately and therefore not blocked, The descriptor might have become used for another queue when a later send() or recv() is performed. The descriptor might then be in blocking mode.

Examples

let mq = posixmq::OpenOptions::readwrite()
    .create_new()
    .max_msg_len(100)
    .capacity(3)
    .open("/with_custom_capacity")
    .expect("create queue");
let attrs = mq.attributes().expect("get attributes for queue");
assert_eq!(attrs.max_msg_len, 100);
assert_eq!(attrs.capacity, 3);
assert_eq!(attrs.current_messages, 0);
assert!(!attrs.nonblocking);

Ignore the error:

(Will only happen with buggy code (incorrect usage of from_raw_fd() or similar)).

let attrs = bad.attributes().unwrap_or_default();
assert_eq!(attrs.max_msg_len, 0);
assert_eq!(attrs.capacity, 0);
assert_eq!(attrs.current_messages, 0);
assert!(!attrs.nonblocking);

pub fn is_nonblocking(&self) -> Result<bool, Error>

Check whether this descriptor is in nonblocking mode.

Errors

Should only fail as result of buggy code that either created this descriptor from something that is not a queue, or has already closed the underlying descriptor.
(This function will not silently succeed if the fd points to anything other than a queue (for example a socket), as this function is a wrapper around [attributes()][#method.attributes].)
To ignore failure, one can write .is_nonblocking().unwrap_or(false).

An error doesn't guarantee that any further send() or recv() wont block.

While a send() or recv() ran in place of this call would also have failed immediately and therefore not blocked, the descriptor might have become used for another queue when a later send() or recv() is performed. The descriptor might then be in blocking mode.

pub fn set_nonblocking(&self, nonblocking: bool) -> Result<(), Error>

Enable or disable nonblocking mode for this descriptor.

This can also be set when opening the message queue, with OpenOptions::nonblocking().

Errors

Setting nonblocking mode should only fail due to incorrect usage of from_raw_fd() or as_raw_fd(), see the documentation on attributes() for details.

pub fn try_clone(&self) -> Result<Self, Error>

Create a new descriptor for the same message queue.

The new descriptor will have close-on-exec set.

This function is not available on FreeBSD, Illumos or Solaris.

pub fn is_cloexec(&self) -> Result<bool, Error>

Check whether this descriptor will be closed if the process execs into another program.

Posix message queues are closed on exec by default, but this can be changed with set_cloexec().

This function is not available on Illumos, Solaris or VxWorks.

Errors

Retrieving this flag should only fail if the descriptor is already closed.
In that case it will obviously not be open after execing, so treating errors as true should be safe.

Examples

let queue = posixmq::PosixMq::create("is_cloexec").expect("open queue");
assert!(queue.is_cloexec().unwrap_or(true));

pub fn set_cloexec(&self, cloexec: bool) -> Result<(), Error>

Change close-on-exec for this descriptor.

It is on by default, so this method should only be called when one wants the descriptor to remain open afte execing.

This function is not available on Illumos, Solaris or VxWorks.

Errors

This function should only fail if the underlying file descriptor has been closed (due to incorrect usage of from_raw_fd() or similar), and not reused for something else yet.

pub unsafe fn from_raw_mqd(mqd: mqd_t) -> Self

Create a PosixMq from an already opened message queue descriptor.

This function should only be used for ffi or if calling mq_open() directly for some reason.
Use from_raw_fd() instead if the surrounding code requires mqd_t to be a file descriptor.

Safety

On some operating systems mqd_t is a pointer, which means that the safety of most other methods depend on it being correct.

pub fn as_raw_mqd(&self) -> mqd_t

Get the raw message queue descriptor.

This function should only be used for passing to ffi code or to access portable features not exposed by this wrapper (such as calling mq_notify() or not automatically retrying on EINTR / ErrorKind::Interrupted when sending or receiving).

If you need a file descriptor, use as_raw_fd() instead for increased portability. (as_raw_fd() can sometimes retrieve an underlying file descriptor even if mqd_t is not an int.)

pub fn into_raw_mqd(self) -> mqd_t

Convert this wrapper into the raw message queue descriptor without closing it.

This function should only be used for ffi; If you need a file descriptor use into_raw_fd() instead.

Trait Implementations

impl AsRawFd for PosixMq

Get an underlying file descriptor for the message queue.

If you just need the raw mqd_t, use as_raw_mqd() instead for increased portability.

This impl is not available on Illumos, Solaris or VxWorks.

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for PosixMq

fn fmt(&self, fmtr: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for PosixMq

fn drop(&mut self)

Executes the destructor for this type.

impl Evented for PosixMq

Allow receiving event notifications through mio (version 0.6).

This impl requires the mio_06 feature to be enabled:

[dependencies]
posixmq = {version="1.0", features=["mio_06"]}

Remember to open the queue in non-blocking mode. (with OpenOptions.noblocking())

fn register(
    &self,
    poll: &Poll,
    token: Token,
    interest: Ready,
    opts: PollOpt
) -> Result<(), Error>

Register self with the given Poll instance.

fn reregister(
    &self,
    poll: &Poll,
    token: Token,
    interest: Ready,
    opts: PollOpt
) -> Result<(), Error>

Re-register self with the given Poll instance.

fn deregister(&self, poll: &Poll) -> Result<(), Error>

Deregister self from the given Poll instance

impl FromRawFd for PosixMq

Create a PosixMq wrapper from a raw file descriptor.

Note that the message queue will be closed when the returned PosixMq goes out of scope / is dropped.

This impl is not available on FreeBSD, Illumos or Solaris; If you got a mqd_t in a portable fashion (from FFI code or by calling mq_open() yourself for some reason), use from_raw_mqd() instead.

unsafe fn from_raw_fd(fd: RawFd) -> Self

Constructs a new instance of Self from the given raw file descriptor.

impl IntoIterator for PosixMq

type Item = (u32, Vec<u8>)

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a PosixMq

type Item = (u32, Vec<u8>)

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Iter<'a>

Creates an iterator from a value.

impl IntoRawFd for PosixMq

Convert the PosixMq into a raw file descriptor without closing the message queue.

This impl is not available on FreeBSD, Illumos or Solaris. If you need to transfer ownership to FFI code accepting a mqd_t, use into_raw_mqd() instead.

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.

impl Send for PosixMq

impl Source for &PosixMq

Allow receiving event notifications through mio (version 0.7).

This impl requires the mio_07 feature to be enabled:

[dependencies]
posixmq = {version="1.0", features=["mio_07"]}

Due to a long-lived bug in cargo this will currently enable the os_reactor feature of mio. This is not intended, and can change in the future.

You probably want to make the queue non-blocking: Either use OpenOptions.noblocking() when preparing to open the queue, or call set_nonblocking(true).

fn register(
    &mut self,
    registry: &Registry,
    token: Token,
    interest: Interest
) -> Result<(), Error>

Register self with the given Registry instance.

fn reregister(
    &mut self,
    registry: &Registry,
    token: Token,
    interest: Interest
) -> Result<(), Error>

Re-register self with the given Registry instance.

fn deregister(&mut self, registry: &Registry) -> Result<(), Error>

Deregister self from the given Registry instance.

impl Source for PosixMq

fn register(
    &mut self,
    registry: &Registry,
    token: Token,
    interest: Interest
) -> Result<(), Error>

Register self with the given Registry instance.

fn reregister(
    &mut self,
    registry: &Registry,
    token: Token,
    interest: Interest
) -> Result<(), Error>

Re-register self with the given Registry instance.

fn deregister(&mut self, registry: &Registry) -> Result<(), Error>

Deregister self from the given Registry instance.