promisqs/
lib.rs

1//! Promisqs (pronounced "promiscuous") is a cross-platform, shared memory,
2//! multi-producer, multi-consumer queue implementation.
3//!
4//! The main use-case for this library is for ultra low latency inter-process communication (IPC),
5//! significantly faster than you would get using any other means, like sockets, UNIX sockets (named pipes
6//! on windows) and even things like DBUS on Linux.
7//! For smaller sized types (a few kB or smaller), Promisqs can easily achieve a latency of a few tenths of a micro-second!
8//!
9//! The queue implementation [`ShmemQueue`](queue/struct.ShmemQueue.html) is generic, allowing most primitive types, and any type that implements the [`FromBytes`](https://docs.rs/zerocopy/latest/zerocopy/trait.FromBytes.html),
10//! [`IntoBytes`](https://docs.rs/zerocopy/latest/zerocopy/trait.IntoBytes.html), and [`Immutable`](https://docs.rs/zerocopy/latest/zerocopy/trait.Immutable.html) traits, to be used with the queue.
11//!
12//! Note that these traits cannot be implemented directly for a type, and must be directly derived, due to safety concerns.
13//! Most primitive types and other fixed size types, like enums, arrays etc.
14//! can be used with the queue. Dynamic types like strings or vectors cannot.
15//!
16//! # Producer Example
17//!
18//! ```
19//! use promisqs::{ShmemQueue, IntoBytes, FromBytes, Immutable};
20//!
21//! // Define a struct that derives zerocopy traits,
22//! // so that we can use it with promisqs queues
23//! #[derive(Debug, Clone, IntoBytes, FromBytes, Immutable, PartialEq)]
24//! pub struct Message {
25//!     id: u8,
26//!     address: [u8; 4],
27//!     payload: [u8; 4],
28//! }
29//!
30//! let mut q = ShmemQueue::<Message>::create("flink.map", 1).unwrap();
31//!
32//! let msg = Message {
33//!     id: 0x0,
34//!     address: [0xc8, 0xa8, 0x1, 0x1],
35//!     payload: [01, 0x2, 0x3, 0x4],
36//! };
37//!
38//! q.push(&msg).unwrap();
39//!
40//! # drop(q);
41//! # std::thread::sleep(std::time::Duration::from_millis(5000));
42//! ```
43//! # Consumer Example (different process)
44//! ```
45//! use promisqs::{ShmemQueue, IntoBytes, FromBytes, Immutable};
46//!
47//! #[derive(Debug, Clone, IntoBytes, FromBytes, Immutable, PartialEq)]
48//! pub struct Message {
49//!     id: u8,
50//!     address: [u8; 4],
51//!     payload: [u8; 4],
52//! }
53//!
54//! # let _q = ShmemQueue::<Message>::create("flink.map", 1).unwrap();
55//! let mut q = ShmemQueue::<Message>::open("flink.map").unwrap();
56//!
57//! let expected_msg = Message {
58//!     id: 0x0,
59//!     address: [0xc8, 0xa8, 0x1, 0x1],
60//!     payload: [01, 0x2, 0x3, 0x4],
61//! };
62//! # q.push(&expected_msg).unwrap();
63//!
64//! assert_eq!(q.pop().unwrap(), expected_msg);
65//!
66//! # drop(_q);
67//! # drop(q);
68//! # std::thread::sleep(std::time::Duration::from_millis(5000));
69//! ```
70
71pub mod error;
72pub mod queue;
73
74pub use error::PromisqsError;
75pub use queue::{PromisqsResult, ShmemQueue};
76
77pub use zerocopy::{FromBytes, Immutable, IntoBytes};
promisqs/lib.rs

promisqs/
lib.rs
