Struct posixmq::PosixMq

pub struct PosixMq { /* fields omitted */ }

A descriptor for an open posix message queue.

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

The descriptor is closed when this struct is dropped.

Methods

impl PosixMq

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

Open an existing message queue in read-only 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
• OS doesn't allow empty messages (EMSGSIZE) => ErrorKind::Other
• Priority is too high (EINVAL) => ErrorKind::InvalidInput
• Possibly other => ErrorKind::Other

pub fn receive(&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
• Possibly other => ErrorKind::Other

pub fn attributes(&self) -> Attributes

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. In that case max_msg_len, capacity and current_messages will be zero and nonblocking is set to true.

The rationale for swallowing these errors is that they're only caused by buggy code (incorrect usage of from_raw_fd() or similar), and not having to .unwrap() makes the function nicer to use.
Future send() and receive() will reveal the bug when they also fail. (Which also means they won't block.)

pub fn is_nonblocking(&self) -> bool

Check whether this descriptor is in nonblocking mode.

Errors

Returns true if retrieving the flag fails, see attributes() for rationale.

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 is_cloexec(&self) -> bool

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

Errors

Retrieving this flag should only fail if the queue is already closed. In that case true is returned because the queue will not be open after execing.

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

Set close-on-exec for this descriptor.

PosixMq enables close-on-exec by default when opening message queues, but this can be disabled with OpenOptions::not_cloexec(). Prefer using OpenOptions to set it, because another thread might exec between the message queue being opened and this change taking effect.

Additionally, this function has a race condition with itself, as the flag cannot portably be set atomically without affecting other attributes.

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.

Trait Implementations

impl Drop for PosixMq

fn drop(&mut self)

Executes the destructor for this type.

impl Send for PosixMq

impl Debug for PosixMq

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

Formats the value using the given formatter.

impl FromRawFd for PosixMq

Create a PosixMq handle from a raw file descriptor.

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

unsafe fn from_raw_fd(fd: RawFd) -> Self

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

impl AsRawFd for PosixMq

Get the raw file descriptor for the queue.

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

This impl is not available on DragonFlyBSD.

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl IntoRawFd for PosixMq

Convert the PosixMq into a raw file descriptor.

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.

impl Evented for PosixMq

Make posix message queues pollable by mio.

This impl requires the mio feature to be enabled:

[dependencies]
posixmq = {version="0.1", features="mio"}

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