How to install the ipmb crate // Lib.rs

Adding `ipmb` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add ipmb

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

ipmb = "0.8.5"

The ipmb library will be automatically available globally. Read the ipmb library documentation.

Back to the crate overview.

Readme

An interprocess message bus system built in Rust, which can be used to pass messages between multiple processes, even including kernel objects (HANDLE/MachPort/FD).

Goals

Easy to use: join, send, recv, that's everything
Bus architecture: No server or client, messages can be freely transmitted among multiple endpoints
Message typing: An endpoint can send or receive multiple message types simultaneously without all endpoints defining a complete global message structure
Practical features: Object, Memory Region, Selector and so on

Getting Started

[dependencies]
ipmb = "0.8"

earth.rs:

use ipmb::label;

fn main () -> Result<(), Box<dyn Error>> {
    // Join your bus 
    let options = ipmb::Options::new("com.solar", label!("earth"), "");
    let (sender, receiver) = ipmb::join::<String, String>(options, None)?;

    // Receive messages
    while let Ok(message) = receiver.recv(None) {
        log::info!("received: {}", message.payload);
    }
    Ok(())
}

moon.rs:

use ipmb::label;
use std::thread;
use std::time::Duration;

fn main () -> Result<(), Box<dyn Error>> {
    // Join your bus 
    let options = ipmb::Options::new("com.solar", label!("moon"), "");
    let (sender, receiver) = ipmb::join::<String, String>(options, None)?;

    loop {
        // Create a message
        let selector = ipmb::Selector::unicast("earth");
        let mut message = ipmb::Message::new(selector, "hello world".to_string());

        // Send the message
        sender.send(message)?;
        
        thread::sleep(Duration::from_secs(1));
    }
}

Concepts

Identifier

An identifier is a system-level unique name for a bus, and only endpoints on the same bus can communicate with each other. On macOS, it will be used to register the MachPort service, on Windows, it will be used to create the corresponding named pipe, and on Linux, it will be used to bind abstract socket address.

Label

Label is the description of an endpoint, and a message can be routed to an endpoint with a LabelOp. A label can contain multiple elements, such as label!("renderer", "codec").

Selector

Selector is used to describe the routing rules of the message, which consists of 2 parts:

SelectorMode: Specify how to consume the message when multiple endpoints satisfy routing rules at the same time.
- Unicast: Only one endpoint can consume this message
- Multicast: All endpoints can consume this message
LabelOp: Describe the matching rules of label, and supports logical operations of AND/OR/NOT.

Payload

Payload is the body content of a message, and its type can be specified by the type parameter of the join function. You can define your own message types:

[dependencies]
type-uuid = "0.1.2"

use serde::{Deserialize, Serialize};
use type_uuid::TypeUuid;

#[derive(Debug, Serialize, Deserialize, TypeUuid)]
#[uuid = "7b07473e-9659-4d47-a502-8245d71c0078"]
struct MyMessage {
    foo: i32,
    bar: bool,
}

fn main() -> Result<(), Box<dyn Error>> {
    let (sender, receiver) = ipmb::join::<MyMessage, MyMessage>(..)?;
    Ok(())
}

MessageBox

MessageBox is a container for multiple message types, allowing endpoints to send/receive multiple message types.

use ipmb::MessageBox;

#[derive(MessageBox)]
enum MultipleMessage {
   String(String),
   I32(i32),
   MyMessage(MyMessage),
}

fn main() -> Result<(), Box<dyn Error>> {
    let (sender, receiver) = ipmb::join::<MultipleMessage, MultipleMessage>(..)?;
    Ok(())
}

Object

Object is the kernel object representation, MachPort on macOS, HANDLE on Windows, FD on Linux, ipmb supports sending Object as message attachment to other endpoints.

fn main () {
   let mut message = ipmb::Message::new(..);
   let obj = unsafe { ipmb::Object::from_raw(libc::mach_task_self()) };
   message.objects.push(obj);
}

MemoryRegion

MemoryRegion is a shared memory block, ipmb supports sending MemoryRegion as message attachment to other endpoints without copying.

fn main() -> Result<(), Box<dyn Error>>{
   let mut message = ipmb::Message::new(..);
   let mut region = ipmb::MemoryRegion::new(16 << 10);
   let view = region.map(..)?;
   writeln!(view, "Hello")?;
   message.memory_regions.push(region);
   Ok(())
}

MemoryRegistry

Efficiently performs many MemoryRegions allocation by sharing and reusing MemoryRegions.

fn main() {
   let mut registry = ipmb::MemoryRegistry::default();
   // Alloc memory region from the registry
   let mut region = registry.alloc(8 << 20, None);
}

Language Bindings

C/C++: ipmb-ffi provides ipmb_ffi.h/ipmb.h, prebuilt libraries can be downloaded here
Node.js: ipmb-js provides node package ()

Supported Platforms

Platform
macOS	✅
Windows	✅
Linux	✅

Benchmark

Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz, macOS 13.4

[2023-06-29T08:54:48Z INFO  bench]       16 B    752,469/s    12.0 MB/s
[2023-06-29T08:54:48Z INFO  bench]       64 B    437,096/s    28.0 MB/s
[2023-06-29T08:54:48Z INFO  bench]     1.0 KB    412,224/s   422.1 MB/s
[2023-06-29T08:54:48Z INFO  bench]     4.1 KB    327,748/s     1.3 GB/s
[2023-06-29T08:54:49Z INFO  bench]    16.4 KB     33,261/s   544.9 MB/s

License

ipmb is dual-licensed:

Adding ipmb library as a dependency

Adding `ipmb` library as a dependency