promisqs/
lib.rs

1//! Promisqs (pronounced "promiscuous") 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//! **NOTE** - In order to implement these traits for your type, you must add [`zerocopy`](https://docs.rs/zerocopy/latest/zerocopy/) as a dependency to your crate.
17//!
18//! # Producer Example
19//!
20//! ```
21//! use promisqs::{ShmemQueue, IntoBytes, FromBytes, Immutable};
22//!
23//! // Define a struct that derives `zerocopy` traits,
24//! // so that we can use it with promisqs queues
25//! #[derive(Debug, Clone, IntoBytes, FromBytes, Immutable, PartialEq)]
26//! pub struct Message {
27//!     id: u8,
28//!     address: [u8; 4],
29//!     payload: [u8; 4],
30//! }
31//!
32//! let mut q = ShmemQueue::<Message>::create("flink.map", 1).unwrap();
33//!
34//! let msg = Message {
35//!     id: 0x0,
36//!     address: [0xc8, 0xa8, 0x1, 0x1],
37//!     payload: [01, 0x2, 0x3, 0x4],
38//! };
39//!
40//! q.push(&msg).unwrap();
41//!
42//! # drop(q);
43//! # std::thread::sleep(std::time::Duration::from_millis(100));
44//! ```
45//! # Consumer Example (different process)
46//! ```
47//! use promisqs::{ShmemQueue, IntoBytes, FromBytes, Immutable};
48//!
49//! #[derive(Debug, Clone, IntoBytes, FromBytes, Immutable, PartialEq)]
50//! pub struct Message {
51//!     id: u8,
52//!     address: [u8; 4],
53//!     payload: [u8; 4],
54//! }
55//!
56//! # let _q = ShmemQueue::<Message>::create("flink.map", 1).unwrap();
57//! let mut q = ShmemQueue::<Message>::open("flink.map").unwrap();
58//!
59//! let expected_msg = Message {
60//!     id: 0x0,
61//!     address: [0xc8, 0xa8, 0x1, 0x1],
62//!     payload: [01, 0x2, 0x3, 0x4],
63//! };
64//! # q.push(&expected_msg).unwrap();
65//!
66//! assert_eq!(q.pop().unwrap(), expected_msg);
67//!
68//! # drop(_q);
69//! # drop(q);
70//! # std::thread::sleep(std::time::Duration::from_millis(100));
71//! ```
72
73pub mod error;
74pub mod queue;
75
76pub use error::PromisqsError;
77pub use queue::{PromisqsResult, ShmemQueue};
78
79pub use zerocopy::{FromBytes, Immutable, IntoBytes};
promisqs/lib.rs

promisqs/
lib.rs
