7 releases (4 breaking)

0.5.1 May 24, 2021
0.5.0 Feb 1, 2021
0.4.0 Jan 9, 2021
0.3.1 Oct 15, 2020
0.1.0 Jun 18, 2019

#746 in Concurrency

Download history 120/week @ 2024-03-14 112/week @ 2024-03-21 107/week @ 2024-03-28 60/week @ 2024-04-04 17/week @ 2024-04-11 11/week @ 2024-04-18 23/week @ 2024-04-25 37/week @ 2024-05-02 8/week @ 2024-05-09 24/week @ 2024-05-16 17/week @ 2024-05-23 25/week @ 2024-05-30 31/week @ 2024-06-06 20/week @ 2024-06-13 20/week @ 2024-06-20 14/week @ 2024-06-27

87 downloads per month

MIT license

54KB
1K SLoC

ipmpsc

Inter-Process Multiple Producer, Single Consumer Channels for Rust

Crates.io Build Status MIT licensed

Summary

This library provides a type-safe, high-performance inter-process channel implementation based on a shared memory ring buffer. It uses bincode for (de)serialization, including zero-copy deserialization, making it ideal for messages with large &str or &[u8] fields. And it has a name that rolls right off the tongue.

Examples

The examples directory contains a sender and receiver pair, which you can run in separate terminals like so:

cargo run --example ipmpsc-receive -- --zero-copy /tmp/ipmpsc
cargo run --example ipmpsc-send -- /tmp/ipmpsc

Type some lines of text into the sender and observe that they are printed by the receiver. You can also run additional senders from other terminals -- the receiver will receive messages from any of them.

Performance

ipmpsc::Receiver::zero_copy_context, used in combination with serde_bytes, is capable of supporting very high bandwidth, low latency transfers (e.g. uncompressed video frames).

See the ipc-benchmarks subcrate for a few simple benchmarks that compare ipmpsc to ipc_channel's high- and low-level interfaces. Here are the results from my Ubuntu laptop:

test tests::bench_ipc_channel       ... bench:  16,013,621 ns/iter (+/- 932,033)
test tests::bench_ipc_channel_bytes ... bench:   4,777,240 ns/iter (+/- 242,369)
test tests::bench_ipmpsc            ... bench:   1,380,406 ns/iter (+/- 62,038)

Security and Safety

The ring buffer is backed by a shared memory-mapped file, which means any process with access to that file can read from or write to it depending on its privileges. This may or may not be acceptable depending on the security needs of your application and the environment in which it runs.

Note that zero-copy deserialization can provide shared references to the mapped file, and internally ipmpsc uses both shared and unique references to segments of the file while reading from and writing to the ring buffer. These references are only safe if all processes which access the file obey Rust's memory safety rules (which normally only have meaning within a single process). ipmpsc itself should follow the rules (please report a bug if not), but safety cannot be guaranteed if any process fails to do so.

Platform Support

This library currently works on Linux, Android, and Windows. It does not work reliably on MacOS, unfortunately. See https://github.com/dicej/ipmpsc/issues/4 for details. PRs to fix that are welcome!

Similar Projects

ipc-channel - mature and robust IPC channels. Does not yet support Android, Windows, multiple simultaneous senders, or zero-copy deserialization.

shared_memory - low-level, cross-platform shared memory support. May be used as the basis for a ring-buffer based channel, but does not yet support Android.

Dependencies

~2–12MB
~144K SLoC