Struct MessageQueue

pub struct MessageQueue<T> {
    pub id: i32,
    pub key: i32,
    pub mask: i32,
    pub message_mask: i32,
    pub mode: i32,
    /* private fields */
}

The main message queue type. It holds basic information about a given message queue as well as type data about the content that passes through it.

The PhantomData marker ensures that the queue is locked to (de)serializing a single tyoe.

MessageQueue is quite liberal about the types it accepts. If you are only ever going to send a type, it just requires that the type is Serialize.

If the queue is only ever going to be receiving data, it requires the associated type to be Deserialize.

This allows you to spare some precious bytes.

Note that MessageQueue reports all errors properly, so they should be handled, lest you wish to shoot your leg off.

General Usage Example

Before usage a MessageQueue needs to be initialized through the use of the MessageQueue::init() method. Failure to do so results in the queue refusing to work.

use ipc_rs::MessageQueue;

let my_key = 1234;
let queue = MessageQueue::<String>::new(my_key)
	.create()
	.async()
	.init()?;

queue.send("hello world".to_string(), 24)
	.expect("failed to send a message");

Fields

id: i32

The actual ID of the underlying SysV message queue. This value is ‘unassigned’ until a call to the init() method is made.

key: i32

This is the key that was given when the MessageQueue was created, make sure to use the same key on both sides of the barricade to ensure proper ‘connection’ is estabilised

mask: i32

The bit flags used to create a new queue, see IpcFlags for more info.

message_mask: i32

The bit flags used when sending/receiving a message, they for example affect whether data gets truncated or whether the calls to send() and recv() are blocking or not.

mode: i32

Mode bits, these are an equivalent to those one encounters when working with files in Unix systems, therefore, the 9 least significant bits follow this pattern:

rwxrwxrwx
|_||_||_|
 │  │  │
 │  │  └── others
 │  └── owner's user group
 └── owner

Currently, the execute bits are ignored, so you needn’t worry about them. Therefore, to allow full access to anyone, mode should be set to 0666 aka 0b110_110_110.

Similarly, to make the queue private one would use 0600 aka 0b110_000_000. `

Implementations

impl<T> MessageQueue<T>

pub fn create(self) -> Self

Allow the creation of a new message queue

pub fn exclusive(self) -> Self

Enforce the operation at hand. If create() is also used, init() will fail if the create already exist.

pub fn async(self) -> Self

Adds the NoWait flag to message_mask to make the calls to send() and recv() non-blocking. When there is no message to be received, recv() returns IpcError::NoMessage and similarly, when a message can’t be sent because the queue is full, a nonblocking send() returns IpcError::QueueFull

pub fn mode(self, mode: Mode) -> Self

Sets the mode of a given message queue. See Mode for more information

pub fn auto_kill(self, kill: bool) -> Self

Automatically deletes removes a queue when it goes out of scope. That basically boils down to self.delete() being called during Drop

pub fn delete(&mut self) -> Result<(), IpcError>

Deletes a queue through msgctl()

pub fn init(self) -> Result<Self, IpcError>

Initializes a MessageQueue with the key self.key, proper modes and mask

pub fn new(key: i32) -> Self

Defines a new MessageQueue In the future, it will be possible to use more types of keys (which would be translated to i32 behind the scenes automatically)

impl<'a, T> MessageQueue<T>

where T: Serialize,

pub fn send<I>(&self, src: T, mtype: I) -> Result<(), IpcError>

where I: Into<i64>,

Sends a new message, or tries to (in case of non-blocking calls). If the queue is full, IpcError::QueueFull is returned

impl<'a, T> MessageQueue<T>

where for<'de> T: Deserialize<'de>,

pub fn peek(&self) -> Result<T, IpcError>

Returns a message without removing it from the message queue. Use recv() if you want to consume the message

pub fn recv(&self) -> Result<T, IpcError>

Receives a message, consuming it. If no message is to be received, recv() either blocks or returns IpcError::NoMemory

Trait Implementations

impl<T> Drop for MessageQueue<T>

fn drop(&mut self)

Does nothing unless auto_kill is specified, in which case it deletes the associated queue