Shmipc

https://docs.rs/shmipc
Admin
A high-performance inter-process communication library by ByteDance using shared memory for...
Tokens:147,428
Snippets:1,163
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### New shmipc Configuration

Source: https://docs.rs/shmipc/latest/src/shmipc/config.rs.html

Creates a new shmipc configuration instance using the default values. This is a convenient way to get a starting configuration.

```rust
pub fn new() -> Self {
    Self::default()
}
```

--------------------------------

### starts_with

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Checks if the slice starts with the given `needle` slice.

```APIDOC
## pub fn starts_with(&self, needle: &[T]) -> bool

### Description
Returns `true` if `needle` is a prefix of the slice or equal to the slice.

### Method
N/A (Method on slice)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **needle** (&[T]) - The slice to check as a prefix.

### Response
#### Success Response
- **bool** - `true` if the slice starts with `needle`, `false` otherwise.

### Note
Always returns `true` if `needle` is an empty slice.
```

--------------------------------

### Create a new SessionManagerConfig

Source: https://docs.rs/shmipc/latest/shmipc/session/config/struct.SessionManagerConfig.html

Initializes a new SessionManagerConfig with default values. This is the starting point for configuring session parameters.

```rust
pub fn new() -> Self
```

--------------------------------

### take

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Creates an adaptor to read at most a specified limit of bytes from the buffer.

```APIDOC
## fn take(self, limit: usize) -> Take<Self>

### Description
Creates an adaptor which will read at most `limit` bytes from `self`.

### Parameters
#### Query Parameters
- **limit** (usize) - Required - The maximum number of bytes to read.

### Returns
- `Take<Self>`: An adaptor that limits the number of bytes read from the buffer.
```

--------------------------------

### ClientProtocolAdapter Initialization (V2/V3)

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/adapter.rs.html

Initializes the protocol adapter for a client, negotiating the protocol version with the server. Supports V2 and V3 protocols, with specific handling for MemMapType::MemMapTypeDevShmFile.

```rust
pub fn get_initializer(self) -> Result<ProtocolInitializer, anyhow::Error> {
        // temporarily ensure version compatibility.
        if let MemMapType::MemMapTypeDevShmFile = self.mem_map_type {
            return Ok(ProtocolInitializer::V2(ProtocolInitializerV2::Client(
                V2Client {
                    conn_fd: self.conn_fd,
                    buffer_path: self.buffer_path,
                    queue_path: self.queue_path,
                },
            )));
        }
        // send version to peer
        let mut h = Header([0; HEADER_SIZE].as_mut_ptr());
        let client_version = MAX_SUPPORT_PROTO_VERSION;
        h.encode(
            HEADER_SIZE as u32,
            client_version,
            EventType::TYPE_EXCHANGE_PROTO_VERSION,
        );
        protocol_trace(&h, &[], true);
        block_write_full(self.conn_fd, unsafe {
            std::slice::from_raw_parts(h.0, HEADER_SIZE)
        })?;
        // recv peer's version
        let mut buf = [0u8; HEADER_SIZE];
        let recv_header = wait_event_header(
            self.conn_fd,
            EventType::TYPE_EXCHANGE_PROTO_VERSION,
            &mut buf,
        )
        .map_err(|err| {
            anyhow!(
                "protrocol_initializer_v3 client_init failed, reason:{}",
                err
            )
        })?;
        let server_version = recv_header.version();
        match std::cmp::min(client_version, server_version) {
            2 => Ok(ProtocolInitializer::V2(ProtocolInitializerV2::Client(
                V2Client {
                    conn_fd: self.conn_fd,
                    buffer_path: self.buffer_path,
                    queue_path: self.queue_path,
                },
            ))),
            3 => Ok(ProtocolInitializer::V3(ProtocolInitializerV3::Client(
                V3Client {
                    conn_fd: self.conn_fd,
                    mem_map_type: self.mem_map_type,
                    buffer_fd: self.buffer_fd,
                    queue_fd: self.queue_fd,
                    buffer_path: self.buffer_path,
                    queue_path: self.queue_path,
                },
            ))),
            version => Err(anyhow!(
                "not support the protocol version:{}, max_support_version is {}",
                version,
                MAX_SUPPORT_PROTO_VERSION
            )),
        }
    }
```

--------------------------------

### Get Element Offset in Slice

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Returns the index of an element reference within a slice. Returns `None` if the element reference does not point to the start of an element. This method uses pointer arithmetic and does not compare elements.

```rust
let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));
```

--------------------------------

### Initialize Client Session

Source: https://docs.rs/shmipc/latest/src/shmipc/session/mod.rs.html

Establishes a new client session by connecting to a specified address. It configures session manager settings, including shared memory paths, and handles potential filename length errors.

```rust
pub async fn client<C>(
        session_id: usize,
        epoch_id: u64,
        rand_id: u64,
        sm_config: &mut SessionManagerConfig,
        connect: &C,
        addr: C::Address,
    ) -> Result<Self, Error>
    where
        C: TransportConnect,
        <C::Stream as TransportStream>::ReadHalf: Send + 'static,
        <C::Stream as TransportStream>::WriteHalf: Send + 'static,
    {
        let conn_stream = connect.connect(addr).await?;

        sm_config
            .config_mut()
            .share_memory_path_prefix
            .push_str(&format!("_{}", std::process::id()));
        if let MemMapType::MemMapTypeDevShmFile = sm_config.config().mem_map_type
            && sm_config.config().share_memory_path_prefix.len()
                + EPOCH_INFO_MAX_LEN
                + QUEUE_INFO_MAX_LEN
                > FILE_NAME_MAX_LEN
        {
            return Err(Error::FileNameTooLong);
        }
        if epoch_id > 0 {
            sm_config
                .config_mut()
                .share_memory_path_prefix
                .push_str(&format!("_epoch_{}_{}", epoch_id, rand_id));
        }
```

--------------------------------

### Iterating Over Chunks from the End of a Slice

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Use `rchunks` to get an iterator over non-overlapping slices of a specified size, starting from the end of the original slice. The last chunk may be smaller if the slice length is not a multiple of `chunk_size`.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.rchunks(2);
assert_eq!(iter.next().unwrap(), &['e', 'm']);
assert_eq!(iter.next().unwrap(), &['o', 'r']);
assert_eq!(iter.next().unwrap(), &['l']);
assert!(iter.next().is_none());
```

--------------------------------

### Iterating Over Exact Chunks from the End of a Slice

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Use `rchunks_exact` to get an iterator over non-overlapping slices of a specified size, starting from the end of the original slice. This iterator guarantees that each yielded chunk has the exact `chunk_size`, omitting any trailing elements that do not form a full chunk.

--------------------------------

### ProtocolInitializerV3::init

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/v3.rs.html

Initializes the V3 protocol, acting as either a client or a server. This method orchestrates the necessary steps for establishing the shared memory connection and exchanging protocol versions.

```APIDOC
## ProtocolInitializerV3::init

### Description
Initializes the V3 protocol for either a client or a server. This function handles the setup of shared memory and protocol version exchange.

### Method
- `init(&self) -> Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error>`

### Parameters
- `self`: An instance of `ProtocolInitializerV3` (either `Client` or `Server`).

### Returns
- `Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error>`: Returns a `Result` which, on success, contains an `Option` holding the `BufferManager` and `QueueManager` if applicable, or `None`. On failure, it returns an `anyhow::Error`.

### Usage
```rust
// Example for client initialization
let client_initializer = ProtocolInitializerV3::Client(Client { ... });
match client_initializer.init() {
    Ok(Some((buffer_manager, queue_manager))) => { /* Handle success */ },
    Ok(None) => { /* Initialization complete, no specific return values */ },
    Err(e) => { /* Handle error */ },
}

// Example for server initialization
let server_initializer = ProtocolInitializerV3::Server(Server { ... });
match server_initializer.init() {
    Ok(Some((buffer_manager, queue_manager))) => { /* Handle success */ },
    Ok(None) => { /* Initialization complete, no specific return values */ },
    Err(e) => { /* Handle error */ },
}
```
```

--------------------------------

### get

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Safely gets a reference to an element or subslice by index or range. Returns None if the index or range is out of bounds.

```APIDOC
## pub fn get<I>(&self, index: I) -> Option<&<I as SliceIndex<[T]>>::Output>

### Description
Returns a reference to an element or subslice depending on the type of index. If given a position, returns a reference to the element at that position or `None` if out of bounds. If given a range, returns the subslice corresponding to that range, or `None` if out of bounds.

### Parameters
#### Path Parameters
- **index** (I) - The index or range to access. `I` must implement `SliceIndex<[T]>`.

### Response
- **Option<&<I as SliceIndex<[T]>>::Output>** - A reference to the element or subslice, or None if out of bounds.
```

--------------------------------

### Server Structure and Initialization

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/v2.rs.html

Defines the `Server` struct containing the connection file descriptor and the first event header. The `init` method validates the first event type and then calls `handle_share_memory_by_file_path`.

```rust
pub struct Server {
    pub(crate) conn_fd: RawFd,
    pub(crate) first_event: Header,
}

impl Server {
    pub fn init(&self) -> Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error> {
        if self.first_event.msg_type() != EventType::TYPE_SHARE_MEMORY_BY_FILE_PATH {
            return Err(anyhow!(
                "ProtocolInitializerV2 expect first event is:{}({}),but:{}",
                EventType::TYPE_SHARE_MEMORY_BY_FILE_PATH.inner(),
                EventType::TYPE_SHARE_MEMORY_BY_FILE_PATH,
                self.first_event.msg_type().inner()
            ));
        }
        handle_share_memory_by_file_path(self.conn_fd, &self.first_event)
    }
}
```

--------------------------------

### Safely Getting Elements or Subslices by Index

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

The `get` method allows safe access to elements or subslices using various index types (position or range). It returns `None` if the index is out of bounds.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

--------------------------------

### Client Structure and Initialization

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/v2.rs.html

Defines the `Client` struct holding connection file descriptor, buffer path, and queue path. Its `init` method uses `send_share_memory_by_file_path` for client-side initialization.

```rust
pub struct Client {
    pub(crate) conn_fd: RawFd,
    pub(crate) buffer_path: String,
    pub(crate) queue_path: String,
}

impl Client {
    pub fn init(&self) -> Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error> {
        send_share_memory_by_file_path(self.conn_fd, &self.buffer_path, &self.queue_path, 2)
    }
}
```

--------------------------------

### ServerProtocolAdapter Initialization (V2)

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/adapter.rs.html

Initializes the protocol adapter for a server, reading the client's proposed protocol version. Currently only supports V2 protocol initialization.

```rust
pub fn get_initializer(self) -> Result<ProtocolInitializer, anyhow::Error> {
        // ensure version compatibility
        let mut buf = vec![0u8; HEADER_SIZE];
        let h = block_read_event_header(self.conn_fd, &mut buf)?;
        std::mem::forget(buf);
        match h.version() {
            2 => Ok(ProtocolInitializer::V2(ProtocolInitializerV2::Server(
                V2Server {

```

--------------------------------

### try_get_i8

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Safely gets a signed 8-bit integer from the buffer.

```APIDOC
## fn try_get_i8(&mut self) -> Result<i8, TryGetError>

### Description
Safely gets a signed 8-bit integer from `self`.

### Method
`try_get_i8`

### Parameters
None

### Returns
Result<i8, TryGetError>: Ok(i8) if successful, or Err(TryGetError) if the buffer does not contain enough data.
```

--------------------------------

### try_get_u8

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Safely gets an unsigned 8-bit integer from the buffer.

```APIDOC
## fn try_get_u8(&mut self) -> Result<u8, TryGetError>

### Description
Safely gets an unsigned 8-bit integer from `self`.

### Method
`try_get_u8`

### Parameters
None

### Returns
Result<u8, TryGetError>: Ok(u8) if successful, or Err(TryGetError) if the buffer does not contain enough data.
```

--------------------------------

### Server::init

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/v3.rs.html

Initializes the server side of the V3 protocol. This involves handling the initial version exchange, receiving and mapping shared memory, and sending an acknowledgment back to the client.

```APIDOC
## Server::init

### Description
Initializes the server connection for the V3 protocol. It verifies the initial protocol version, handles the shared memory setup, and acknowledges the client.

### Method
- `init(&self) -> Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error>`

### Parameters
- `&self`: A reference to the `Server` instance, containing the connection file descriptor and the first received event header.

### Returns
- `Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error>`: On success, returns `Ok(Some(buffer_manager, queue_manager))` containing the initialized buffer and queue managers. On failure, returns an `anyhow::Error`.

### Usage
```rust
let server = Server {
    conn_fd: 2,
    first_event: Header([0u8; HEADER_SIZE].as_mut_ptr()), // Assume first_event is properly set
};
match server.init() {
    Ok(Some((buffer_manager, queue_manager))) => {
        println!("Server initialized successfully with buffer and queue managers.");
        // Use buffer_manager and queue_manager
    },
    Ok(None) => unreachable!(), // Server init should return Some
    Err(e) => eprintln!("Server initialization failed: {}", e),
}
```
```

--------------------------------

### Client::init

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/v3.rs.html

Initializes the client side of the V3 protocol. This involves sending shared memory information (either by file path or memfd) to the server and waiting for an acknowledgment.

```APIDOC
## Client::init

### Description
Initializes the client connection for the V3 protocol. It sends the shared memory details to the server and waits for an acknowledgment.

### Method
- `init(&self) -> Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error>`

### Parameters
- `&self`: A reference to the `Client` instance, containing connection details and shared memory paths/file descriptors.

### Returns
- `Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error>`: On success, returns `Ok(None)` as the client does not return buffer/queue managers directly from this init. On failure, returns an `anyhow::Error`.

### Usage
```rust
let client = Client {
    conn_fd: 1,
    mem_map_type: MemMapType::MemMapTypeDevShmFile,
    buffer_path: "/path/to/buffer".to_string(),
    queue_path: "/path/to/queue".to_string(),
    buffer_fd: -1,
    queue_fd: -1,
};
match client.init() {
    Ok(None) => println!("Client initialized successfully."),
    Ok(Some(_)) => unreachable!(), // Client init should return None
    Err(e) => eprintln!("Client initialization failed: {}", e),
}
```
```

--------------------------------

### Get Stream ID

Source: https://docs.rs/shmipc/latest/shmipc/stream/struct.Stream.html

Returns the unique identifier for the stream.

```rust
pub const fn stream_id(&self) -> u32
```

--------------------------------

### SHM IPC Slice Write and Split Example

Source: https://docs.rs/shmipc/latest/src/shmipc/buffer/slice.rs.html

Demonstrates writing to a slice and then splitting it, followed by assertions to verify the state of the slice's back and write pointers, as well as its size. This is useful for understanding buffer manipulation in SHM IPC.

```rust
l.write_slice = l.back_slice;
            }
        }
        l.split_from_write();
        assert_eq!(l.back(), l.write());

        assert_eq!(51, l.size());
```

--------------------------------

### Getting SliceList Size

Source: https://docs.rs/shmipc/latest/src/shmipc/buffer/slice.rs.html

Returns the number of `BufferSlice`s currently in the `SliceList`.

```rust
pub const fn size(&self) -> usize {
    self.len
}
```

--------------------------------

### QueueManager::create_with_file

Source: https://docs.rs/shmipc/latest/src/shmipc/queue.rs.html

Creates a new QueueManager using a file in the filesystem for shared memory. It handles directory creation and permission settings.

```APIDOC
## QueueManager::create_with_file

### Description
Creates a new QueueManager instance by utilizing a file path for shared memory. This method ensures the directory exists, sets permissions, and checks for existing queues before creating the shared memory file.

### Parameters
- `shm_path` (string) - The path to the shared memory file to be created or used.
- `queue_cap` (u32) - The capacity of each queue (send and receive).

### Returns
- `Result<QueueManager, anyhow::Error>` - Ok containing the QueueManager on success, or an Err with an error message on failure.

### Errors
- Returns an error if the queue path already exists.
- Returns an error if there is insufficient space on the device for the requested memory size.

### Example
```rust
// Example usage (assuming necessary imports and context)
// let queue_manager = QueueManager::create_with_file("/dev/shm/my_shm_queue", 1024)?;
```
```

--------------------------------

### Get Session ID

Source: https://docs.rs/shmipc/latest/shmipc/stream/struct.Stream.html

Returns the session ID associated with this stream.

```rust
pub const fn session_id(&self) -> usize
```

--------------------------------

### Create Linked Buffer Slices

Source: https://docs.rs/shmipc/latest/src/shmipc/buffer/slice.rs.html

Demonstrates creating multiple buffer slices, appending data to each, and then linking them together to form a chain. It verifies that data can be read sequentially from the linked slices.

```rust
const SIZE: usize = 8192;
const SLICE_NUM: usize = 100;

let mut slices = Vec::with_capacity(SLICE_NUM);
let mem = MmapOptions::new().len(10 << 20).map_anon().unwrap();
let bm = BufferManager::create(
    &[SizePercentPair { size: 8192, percent: 100 }],
    "",
    mem,
    0,
)
.unwrap();

let mut write_data_array = Vec::with_capacity(100);

for _ in 0..SLICE_NUM {
    let mut s = bm.alloc_shm_buffer(SIZE as u32).unwrap();
    let mut rng = rand::rng();
    let data: Vec<u8> = (0..SIZE).map(|_| rng.random()).collect();
    assert_eq!(s.append(&data), SIZE);
    s.update();
    slices.push(s);
    write_data_array.push(data);
}

for i in 0..slices.len() - 1 {
    slices[i]
        .buffer_header
        .as_ref()
        .unwrap()
        .link_next(slices[i + 1].offset_in_shm);
}

let mut next = slices[0].offset_in_shm;
(0..SLICE_NUM).for_each(|i| {
    let mut s = bm.read_buffer_slice(next).unwrap();
    assert_eq!(s.capacity(), SIZE);
    assert_eq!(s.size(), SIZE);
    let read_data = s.read(SIZE);
    assert_eq!(read_data.len(), SIZE);
    (0..SIZE).for_each(|j| {
        assert_eq!(read_data[j], write_data_array[i][j]);
    });
    let is_last_slice = i == SLICE_NUM - 1;
    assert_eq!(s.buffer_header.as_ref().unwrap().has_next(), !is_last_slice);
    next = s.buffer_header.as_ref().unwrap().next_buffer_offset();
});
```

--------------------------------

### connect

Source: https://docs.rs/shmipc/latest/shmipc/transport/struct.DefaultUnixConnect.html

Establishes a connection to a Unix domain socket address.

```APIDOC
## connect

### Description
Establishes a connection to a Unix domain socket address.

### Method
`async fn connect(&self, addr: Self::Address) -> Result<Self::Stream>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **Stream** (`UnixStream`): The established Unix stream.

#### Response Example
None

### Error Handling
- Returns `Result` which may contain an error if the connection fails.
```

--------------------------------

### Get session number

Source: https://docs.rs/shmipc/latest/shmipc/session/config/struct.SessionManagerConfig.html

Retrieves the configured session number from the SessionManagerConfig.

```rust
pub const fn session_num(&self) -> usize
```

--------------------------------

### try_get_int_ne

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets a signed n-byte integer from the buffer in native-endian byte order.

```APIDOC
## fn try_get_int_ne(&mut self, nbytes: usize) -> Result<i64, TryGetError>

### Description
Gets a signed n-byte integer from `self` in native-endian byte order.

### Parameters
#### Query Parameters
- **nbytes** (usize) - Required - The number of bytes to read for the integer.

### Returns
- `Result<i64, TryGetError>`: A signed 64-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### Client::init

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/v2.rs.html

Initializes the client side of the V2 protocol. It sends shared memory information using the provided connection file descriptor, buffer path, and queue path.

```APIDOC
## Client::init

### Description
Initializes the client for the V2 protocol by sending shared memory details over a file descriptor. This method is used to establish the communication channel from the client's perspective.

### Method
- `init(&self) -> Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error>`

### Parameters
- `self`: A reference to the `Client` struct, containing `conn_fd`, `buffer_path`, and `queue_path`.

### Returns
- `Ok(Some((Arc<BufferManager>, QueueManager)))`: On successful initialization, returns a tuple containing a shared reference to the `BufferManager` and the `QueueManager`.
- `Ok(None)`: If initialization results in no specific resources to return.
- `Err(anyhow::Error)`: If an error occurs during the `send_share_memory_by_file_path` operation.

### Usage
```rust
let client = Client {
    conn_fd: 1,
    buffer_path: "/tmp/shm_buffer".to_string(),
    queue_path: "/tmp/shm_queue".to_string(),
};
match client.init() {
    Ok(Some((buffer_manager, queue_manager))) => {
        println!("Client initialized successfully.");
        // Proceed with using buffer_manager and queue_manager
    },
    Ok(None) => {
        println!("Client initialized, but no specific resources returned.");
    },
    Err(e) => {
        eprintln!("Client initialization failed: {}", e);
    }
}
```
```

--------------------------------

### try_get_int_le

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets a signed n-byte integer from the buffer in little-endian byte order.

```APIDOC
## fn try_get_int_le(&mut self, nbytes: usize) -> Result<i64, TryGetError>

### Description
Gets a signed n-byte integer from `self` in little-endian byte order.

### Parameters
#### Query Parameters
- **nbytes** (usize) - Required - The number of bytes to read for the integer.

### Returns
- `Result<i64, TryGetError>`: A signed 64-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### Buffer Manager Initialization and Usage

Source: https://docs.rs/shmipc/latest/src/shmipc/buffer/manager.rs.html

Initializes a BufferManager with specified file, size, and buffer size/percentage pairs. Demonstrates checking remaining size after initial allocation and then allocating and recycling individual buffers.

```rust
let bm = BufferManager::get_with_file(
            "/tmp/shm11",
            1 << 20,
            true,
            &mut [
                SizePercentPair {
                    size: 4096,
                    percent: 50,
                },
                SizePercentPair {
                    size: 8192,
                    percent: 50,
                },
            ],
        )
        .unwrap();
        // use first two buffer to record buffer list info (List header)
        assert_eq!((1 << 20) - 4096 - 8192, bm.remain_size());

        let num_of_slice = bm.slice_size();
        let mut buffers = Vec::with_capacity(1024);
        while let Ok(s) = bm.alloc_shm_buffer(4096) {
            buffers.push(s);
        }
        for buffer in buffers {
            bm.recycle_buffer(buffer);
        }
```

--------------------------------

### try_get_int

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets a signed n-byte integer from the buffer in big-endian byte order.

```APIDOC
## fn try_get_int(&mut self, nbytes: usize) -> Result<i64, TryGetError>

### Description
Gets a signed n-byte integer from `self` in big-endian byte order.

### Parameters
#### Query Parameters
- **nbytes** (usize) - Required - The number of bytes to read for the integer.

### Returns
- `Result<i64, TryGetError>`: A signed 64-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### SliceList::new

Source: https://docs.rs/shmipc/latest/src/shmipc/buffer/slice.rs.html

Creates a new, empty SliceList.

```APIDOC
## SliceList::new

### Description
Creates a new, empty `SliceList`.

### Method
`const fn new() -> Self`

### Returns
A new `SliceList` instance.
```

--------------------------------

### try_get_uint_ne

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets an unsigned n-byte integer from the buffer in native-endian byte order.

```APIDOC
## fn try_get_uint_ne(&mut self, nbytes: usize) -> Result<u64, TryGetError>

### Description
Gets an unsigned n-byte integer from `self` in native-endian byte order.

### Parameters
#### Query Parameters
- **nbytes** (usize) - Required - The number of bytes to read for the integer.

### Returns
- `Result<u64, TryGetError>`: An unsigned 64-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### Handle Share Memory by Memfd

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/mod.rs.html

Handles the reception and setup of shared memory using memfd. This involves receiving metadata, acknowledging readiness, receiving file descriptors, and mapping the shared memory regions.

```APIDOC
/// Handles the process of receiving and setting up shared memory via memfd.
/// This function orchestrates the receiving of metadata, sending acknowledgments,
/// receiving file descriptors, and mapping the shared memory for BufferManager and QueueManager.
///
/// # Arguments
///
/// * `conn_fd` - The file descriptor of the connection.
/// * `h` - The header received from the peer, containing metadata length.
/// * `version` - The protocol version being used.
///
/// # Returns
///
/// A Result containing an Option of `(Arc<BufferManager>, QueueManager)` on success,
/// or an error if any step fails.
pub fn handle_share_memory_by_memfd(
    conn_fd: RawFd,
    h: &Header,
    version: u8,
) -> Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error>;
```

--------------------------------

### Generic Implementations for SizePercentPair

Source: https://docs.rs/shmipc/latest/shmipc/config/struct.SizePercentPair.html

Demonstrates various blanket implementations for SizePercentPair, including Any, Borrow, BorrowMut, From, Into, ToOwned, TryFrom, TryInto, and WithSubscriber. These provide common functionalities and interoperability.

```rust
impl<T> Any for T
where T: 'static + ?Sized,
fn type_id(&self) -> TypeId
```

```rust
impl<T> Borrow<T> for T
where T: ?Sized,
fn borrow(&self) -> &T
```

```rust
impl<T> BorrowMut<T> for T
where T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
```

```rust
impl<T> CloneToUninit for T
where T: Clone,
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

```rust
impl<T> From<T> for T
fn from(t: T) -> T
```

```rust
impl<T> Instrument for T
fn instrument(self, span: Span) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
```

```rust
impl<T, U> Into<U> for T
where U: From<T>,
fn into(self) -> U
```

```rust
impl<T> ToOwned for T
where T: Clone,
type Owned = T
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)
```

```rust
impl<T, U> TryFrom<U> for T
where U: Into<T>,
type Error = Infallible
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

```rust
impl<T, U> TryInto<U> for T
where U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

```rust
impl<T> WithSubscriber for T
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,
fn with_current_subscriber(self) -> WithDispatch<Self>
```

```rust
impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>
```

--------------------------------

### try_get_uint_le

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets an unsigned n-byte integer from the buffer in little-endian byte order.

```APIDOC
## fn try_get_uint_le(&mut self, nbytes: usize) -> Result<u64, TryGetError>

### Description
Gets an unsigned n-byte integer from `self` in little-endian byte order.

### Parameters
#### Query Parameters
- **nbytes** (usize) - Required - The number of bytes to read for the integer.

### Returns
- `Result<u64, TryGetError>`: An unsigned 64-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### try_get_uint

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets an unsigned n-byte integer from the buffer in big-endian byte order.

```APIDOC
## fn try_get_uint(&mut self, nbytes: usize) -> Result<u64, TryGetError>

### Description
Gets an unsigned n-byte integer from `self` in big-endian byte order.

### Parameters
#### Query Parameters
- **nbytes** (usize) - Required - The number of bytes to read for the integer.

### Returns
- `Result<u64, TryGetError>`: An unsigned 64-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### try_get_i128_ne

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets a signed 128-bit integer from the buffer in native-endian byte order.

```APIDOC
## fn try_get_i128_ne(&mut self) -> Result<i128, TryGetError>

### Description
Gets a signed 128-bit integer from `self` in native-endian byte order.

### Parameters
None

### Returns
- `Result<i128, TryGetError>`: A signed 128-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### BufferList Creation and Mapping Tests

Source: https://docs.rs/shmipc/latest/src/shmipc/buffer/list.rs.html

Tests various scenarios for creating and mapping BufferLists, including invalid parameters and memory mapping configurations. Asserts expected error conditions.

```rust
    #[test]
    fn test_buffer_list_create_and_mapping_free_buffer_list() {
        let cap_per_buffer = 16;
        let buffer_num = 10;
        let mem = MmapOptions::new()
            .len(count_buffer_list_mem_size(buffer_num, cap_per_buffer) as usize)
            .map_anon()
            .unwrap();
        let l = BufferList::create(0, cap_per_buffer, &mem, 0);
        assert!(l.is_err());

        let l = BufferList::create(buffer_num + 1, cap_per_buffer, &mem, 0);
        assert!(l.is_err());

        let _ = BufferList::create(buffer_num, cap_per_buffer, &mem, 0).unwrap();

        let test_mem = std::sync::Arc::new(MmapOptions::new().len(10).map_anon().unwrap());
        let ml = BufferList::mapping(&test_mem, 0);
        assert!(ml.is_err());

        let ml = BufferList::mapping(&mem, 8);
        assert!(ml.is_err());

        let _ = BufferList::mapping(&mem, 0).unwrap();
    }
```

--------------------------------

### ProtocolInitializerV2::version

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/v2.rs.html

Returns the version number of the V2 protocol initializer.

```APIDOC
## ProtocolInitializerV2::version

### Description
Provides the version identifier for the V2 protocol initializer.

### Method
- `version() -> u8`

### Returns
- `2`: The constant version number for this protocol initializer.

### Usage
```rust
let version = ProtocolInitializerV2::version();
println!("Protocol Version: {}", version);
```
```

--------------------------------

### try_get_i128_le

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets a signed 128-bit integer from the buffer in little-endian byte order.

```APIDOC
## fn try_get_i128_le(&mut self) -> Result<i128, TryGetError>

### Description
Gets a signed 128-bit integer from `self` in little-endian byte order.

### Parameters
None

### Returns
- `Result<i128, TryGetError>`: A signed 128-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### ProtocolInitializerV2::init

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/v2.rs.html

Initializes the protocol initializer, acting as either a client or a server. It returns a tuple containing an Arc<BufferManager> and a QueueManager upon successful initialization, or an error if the process fails.

```APIDOC
## ProtocolInitializerV2::init

### Description
Initializes the protocol initializer, which can be configured as either a client or a server. This method sets up the necessary shared memory and queue resources.

### Method
- `init(&self) -> Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error>`

### Parameters
- `self`: A reference to the `ProtocolInitializerV2` instance (either `Client` or `Server`).

### Returns
- `Ok(Some((Arc<BufferManager>, QueueManager)))`: On successful initialization, returns a tuple containing a shared reference to the `BufferManager` and the `QueueManager`.
- `Ok(None)`: If initialization results in no specific resources to return (though the current implementation always returns `Some` on success).
- `Err(anyhow::Error)`: If any error occurs during the initialization process.

### Usage
```rust
// Example for Client
let client_initializer = ProtocolInitializerV2::Client(Client { conn_fd: 0, buffer_path: "/path/to/buffer".to_string(), queue_path: "/path/to/queue".to_string() });
match client_initializer.init() {
    Ok(Some((buffer_manager, queue_manager))) => {
        // Use buffer_manager and queue_manager
    },
    Ok(None) => {
        // Initialization succeeded but returned no resources
    },
    Err(e) => {
        // Handle initialization error
        eprintln!("Initialization failed: {}", e);
    }
}

// Example for Server
// Assuming `first_event` is a valid Header object
// let server_initializer = ProtocolInitializerV2::Server(Server { conn_fd: 0, first_event: first_event });
// match server_initializer.init() {
//     Ok(Some((buffer_manager, queue_manager))) => {
//         // Use buffer_manager and queue_manager
//     },
//     Ok(None) => {
//         // Initialization succeeded but returned no resources
//     },
//     Err(e) => {
//         // Handle initialization error
//         eprintln!("Initialization failed: {}", e);
//     }
// }
```
```

--------------------------------

### try_get_i128

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets a signed 128-bit integer from the buffer in big-endian byte order.

```APIDOC
## fn try_get_i128(&mut self) -> Result<i128, TryGetError>

### Description
Gets a signed 128-bit integer from `self` in big-endian byte order.

### Parameters
None

### Returns
- `Result<i128, TryGetError>`: A signed 128-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### try_get_u128_ne

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets an unsigned 128-bit integer from the buffer in native-endian byte order.

```APIDOC
## fn try_get_u128_ne(&mut self) -> Result<u128, TryGetError>

### Description
Gets an unsigned 128-bit integer from `self` in native-endian byte order.

### Parameters
None

### Returns
- `Result<u128, TryGetError>`: An unsigned 128-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### Splitting a Slice into SIMD and Scalar Parts

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Demonstrates how to split a slice into SIMD-compatible prefix, middle, and suffix parts using `as_simd`. Useful for processing data with SIMD instructions.

```rust
#![feature(portable_simd)]
use core::simd::prelude::*;

let short = &[1, 2, 3];
let (prefix, middle, suffix) = short.as_simd::<4>();
assert_eq!(middle, []); // Not enough elements for anything in the middle

// They might be split in any possible way between prefix and suffix
let it = prefix.iter().chain(suffix).copied();
assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);

fn basic_simd_sum(x: &[f32]) -> f32 {
    use std::ops::Add;
    let (prefix, middle, suffix) = x.as_simd();
    let sums = f32x4::from_array([
        prefix.iter().copied().sum(),
        0.0,
        0.0,
        suffix.iter().copied().sum(),
    ]);
    let sums = middle.iter().copied().fold(sums, f32x4::add);
    sums.reduce_sum()
}

let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);

```

--------------------------------

### Server::init

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/v2.rs.html

Initializes the server side of the V2 protocol. It handles the reception and processing of shared memory information, ensuring the first event is of the expected type.

```APIDOC
## Server::init

### Description
Initializes the server for the V2 protocol. This method verifies that the initial incoming message is of type `TYPE_SHARE_MEMORY_BY_FILE_PATH` and then processes it to set up shared memory resources.

### Method
- `init(&self) -> Result<Option<(Arc<BufferManager>, QueueManager)>, anyhow::Error>`

### Parameters
- `self`: A reference to the `Server` struct, containing `conn_fd` and `first_event`.

### Returns
- `Ok(Some((Arc<BufferManager>, QueueManager)))`: On successful initialization, returns a tuple containing a shared reference to the `BufferManager` and the `QueueManager`.
- `Ok(None)`: If initialization results in no specific resources to return.
- `Err(anyhow::Error)`: If the `first_event` is not of the expected type or if `handle_share_memory_by_file_path` fails.

### Usage
```rust
// Assume `header` is a valid Header object received from the client
// let server = Server {
//     conn_fd: 0,
//     first_event: header,
// };
// match server.init() {
//     Ok(Some((buffer_manager, queue_manager))) => {
//         println!("Server initialized successfully.");
//         // Proceed with using buffer_manager and queue_manager
//     },
//     Ok(None) => {
//         println!("Server initialized, but no specific resources returned.");
//     },
//     Err(e) => {
//         eprintln!("Server initialization failed: {}", e);
//     }
// }
```
```

--------------------------------

### try_get_u128_le

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets an unsigned 128-bit integer from the buffer in little-endian byte order.

```APIDOC
## fn try_get_u128_le(&mut self) -> Result<u128, TryGetError>

### Description
Gets an unsigned 128-bit integer from `self` in little-endian byte order.

### Parameters
None

### Returns
- `Result<u128, TryGetError>`: An unsigned 128-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### try_get_u128

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets an unsigned 128-bit integer from the buffer in big-endian byte order.

```APIDOC
## fn try_get_u128(&mut self) -> Result<u128, TryGetError>

### Description
Gets an unsigned 128-bit integer from `self` in big-endian byte order.

### Parameters
None

### Returns
- `Result<u128, TryGetError>`: An unsigned 128-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### Create a new SessionManager

Source: https://docs.rs/shmipc/latest/shmipc/session/manager/struct.SessionManager.html

Initializes a new SessionManager instance. Requires configuration, a transport connector, and an address.

```rust
pub async fn new( sm_config: SessionManagerConfig, connect: C, addr: C::Address, ) -> Result<Self, Error>
```

--------------------------------

### Clone to Uninit (Experimental)

Source: https://docs.rs/shmipc/latest/shmipc/buffer/list/struct.BufferList.html

An experimental nightly-only API for performing copy-assignment to uninitialized memory.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### try_get_i64_ne

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets a signed 64-bit integer from the buffer in native-endian byte order.

```APIDOC
## fn try_get_i64_ne(&mut self) -> Result<i64, TryGetError>

### Description
Gets a signed 64-bit integer from `self` in native-endian byte order.

### Parameters
None

### Returns
- `Result<i64, TryGetError>`: A signed 64-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### ProtocolInitializerV3::version

Source: https://docs.rs/shmipc/latest/src/shmipc/protocol/initializer/v3.rs.html

Returns the version number of the V3 protocol.

```APIDOC
## ProtocolInitializerV3::version

### Description
Provides the static version number for the V3 protocol initializer.

### Method
- `version() -> u8`

### Returns
- `u8`: The constant value `3`, indicating the protocol version.

### Usage
```rust
let version = ProtocolInitializerV3::version();
println!("Protocol Version: {}", version); // Output: Protocol Version: 3
```
```

--------------------------------

### try_get_i64_le

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets a signed 64-bit integer from the buffer in little-endian byte order.

```APIDOC
## fn try_get_i64_le(&mut self) -> Result<i64, TryGetError>

### Description
Gets a signed 64-bit integer from `self` in little-endian byte order.

### Parameters
None

### Returns
- `Result<i64, TryGetError>`: A signed 64-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### BufferSlice::new

Source: https://docs.rs/shmipc/latest/src/shmipc/buffer/slice.rs.html

Creates a new BufferSlice. Initializes capacity, start, and write index based on whether it's from shared memory and has a buffer header.

```APIDOC
## BufferSlice::new

### Description
Creates a new `BufferSlice` instance. It initializes the slice's properties such as capacity, start, and write index. If the slice is intended to be from shared memory and a `BufferHeader` is provided, it uses the header's information; otherwise, it uses the provided data slice's length for capacity.

### Parameters
* `header`: `Option<BufferHeader>` - The buffer header, if available (for shared memory buffers).
* `data`: `&mut [u8]` - A mutable slice of bytes representing the buffer's data.
* `offset_in_shm`: `u32` - The offset of this buffer slice within the shared memory.
* `is_from_shm`: `bool` - A flag indicating whether this buffer slice originates from shared memory.

### Returns
* `Self` - A new `BufferSlice` instance.
```

--------------------------------

### try_get_i64

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets a signed 64-bit integer from the buffer in big-endian byte order.

```APIDOC
## fn try_get_i64(&mut self) -> Result<i64, TryGetError>

### Description
Gets a signed 64-bit integer from `self` in big-endian byte order.

### Parameters
None

### Returns
- `Result<i64, TryGetError>`: A signed 64-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### try_get_u64_ne

Source: https://docs.rs/shmipc/latest/shmipc/buffer/enum.Buf.html

Gets an unsigned 64-bit integer from the buffer in native-endian byte order.

```APIDOC
## fn try_get_u64_ne(&mut self) -> Result<u64, TryGetError>

### Description
Gets an unsigned 64-bit integer from `self` in native-endian byte order.

### Parameters
None

### Returns
- `Result<u64, TryGetError>`: An unsigned 64-bit integer if successful, or a `TryGetError` if the operation fails.
```

--------------------------------

### BufferHeader PartialEq Implementation

Source: https://docs.rs/shmipc/latest/shmipc/buffer/slice/struct.BufferHeader.html

Illustrates the implementation of the PartialEq trait for BufferHeader, allowing for equality comparisons between BufferHeader instances.

```rust
impl PartialEq for BufferHeader
Source
#### fn eq(&self, other: &BufferHeader) -> bool
Tests for `self` and `other` values to be equal, and is used by `==`.
1.0.0 · Source
#### fn ne(&self, other: &Rhs) -> bool
Tests for `!=`. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source
```
Tokens:
Raw