FDRingbuf

https://docs.rs/fdringbuf/0.0.2/fdringbuf/
Admin
FDRingbuf is a fast Rust ringbuffer library that minimizes memory copies and provides file...
Tokens:4,589
Snippets:52
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Search Functions by Type Signature

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel_bufsize.html

Search for functions by their type signature, for example, `vec -> usize` or `* -> vec`. This is a search trick to refine queries.

```text
vec -> usize
* -> vec
```

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

### Get Wait Status

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/struct.Receiver.html

The wait_status method returns a file descriptor (RawFd) to wait for and the number of items that can be read. Waiting should only occur if the number of readable items is zero. The file descriptor remains constant.

```rust
fn wait_status(&self) -> (RawFd, usize)
```

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

### Get Writable Item Count

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/struct.Sender.html

Returns the number of items that can currently be written to the buffer.

```rust
fn write_count(&self) -> usize
```

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

### Get Read Count

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/struct.Receiver.html

The read_count method returns the number of items currently available to be read from the buffer.

```rust
fn read_count(&self) -> usize
```

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

### Show Help Dialog

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel_bufsize.html

Press '?' to display this help dialog. This is a keyboard shortcut for navigating the documentation.

```text
?
```

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

### fdringbuf Help and Search

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/index.html

Information on keyboard shortcuts and search tricks for navigating the documentation.

```APIDOC
## Help

### Keyboard Shortcuts

*   `?`: Show this help dialog
*   `S`: Focus the search field
*   `⇤`: Move up in search results
*   `⇥`: Move down in search results
*   `⏎`: Go to active search result
*   `+`: Collapse/expand all sections

### Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type. Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)
```

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

### fdringbuf Crate Overview

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/index.html

Overview of the fdringbuf crate, its modules, and platform information.

```APIDOC
## Crate fdringbuf [−] [src]

### Modules

*   **fdbuf**: Ringbuffer with signalling via fd:s. You can use it with `std::os::Pipe`, but do try `nix-rust`'s eventfds for slightly better performance! You will typically integrate with `mio` so you can wait for many fds at once, hence there are no functions that actually wait, just functions that give out the Fd to wait for.
*   **ringbuf**: This is a fast ringbuffer that tries to avoid memory copies as much as possible. There can be one producer and one consumer, but they can be in different threads i.e., they are `Send` but not `Clone`.

### Platform

*   [Platform information if available]

### Feature flags

*   [Feature flags if available]
```

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

### fdringbuf Channel Creation

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/index.html

Demonstrates how to create a signaling channel using the `channel` function in fdringbuf.

```APIDOC
## Function channel

### Description
Creates a channel with fd signalling. Does not take ownership of the fds - they will not be closed when Sender and Receiver goes out of scope.

### Method
(Implied: Likely a constructor or factory function, specific HTTP method not applicable in this context)

### Endpoint
(Not applicable for library functions)

### Parameters
(Specific parameters for `channel` function are not detailed in the provided text, but it would typically involve creating or returning file descriptors.)

### Request Example
(Not applicable for library functions)

### Response
#### Success Response
- **Sender** (type) - A sender half of the channel.
- **Receiver** (type) - A receiver half of the channel.

### Response Example
(Specific response structure not detailed in the provided text.)
```

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

### Collapse/Expand All Sections

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel_bufsize.html

Press '+' to collapse or expand all sections. This is a keyboard shortcut for managing the visibility of documentation sections.

```text
+

```

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

### fdringbuf Module Overview

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/index.html

Provides an overview of the fdringbuf module, its purpose, and key components.

```APIDOC
## Module fdringbuf::fdbuf

### Description
Ringbuffer with signalling via fd:s. You can use it with std::os::Pipe, but do try nix-rust's eventfds for slightly better performance! You will typically integrate with mio so you can wait for many fds at once, hence there are no functions that actually wait, just functions that give out the Fd to wait for.

### Structs
- **Receiver**
- **Sender**

### Functions
- **channel** - Creates a channel with fd signalling. Does not take ownership of the fds - they will not be closed when Sender and Receiver goes out of scope.
```

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

### Create a channel with fd signalling

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/fn.channel.html

Initializes a channel using the provided byte slice and pipes. Note that the function does not take ownership of the file descriptors.

```rust
pub fn channel<'a, T: Copy>(  
    slice: &'a mut [u8],   
    empty: Pipe,   
    full: Pipe  
) -> (Sender<'a, T>, Receiver<'a, T>)
```

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

### Create a ring buffer channel

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel.html

Initializes a channel using a provided mutable byte slice. This function does not perform heap allocation.

```rust
pub fn channel<'a, T: Copy>(  
    slice: &'a mut [u8]  
) -> (Sender<'a, T>, Receiver<'a, T>)
```

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

### Receiver Methods

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/struct.Receiver.html

API documentation for the methods available on the Receiver struct.

```APIDOC
## fn recv<F: FnMut(&[T]) -> (usize, bool)>(&mut self, f: F) -> Result<usize>

### Description
Returns remaining items that can be read. The closure f returns a tuple of (items written, please call me again). The second item is true if the buffer was full but read from, which can be used to signal the remote side that more data can be written.

## fn wait_status(&self) -> (RawFd, usize)

### Description
Returns the file descriptor to wait for and the number of items that can be read. You should only wait for this file descriptor if the number of items is zero. The file descriptor will not change during the lifetime of the sender.

## fn wait_clear(&mut self) -> Result<()>

### Description
Call this after being woken up by the waitfd to clear the state. Note: Might deadlock if called when not woken up by the waitfd.
```

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

### Sender Methods

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/struct.Sender.html

Methods available for the Sender struct.

```APIDOC
## Methods for impl<'a, T: Copy> Sender<'a, T>

### `fn send<F: FnMut(&mut [T]) -> usize>(&mut self, f: F) -> (usize, bool)`

#### Description
Sends data to the ring buffer using a closure. Returns a tuple containing the number of free items available in the buffer and a boolean indicating if the buffer was initially empty.

#### Parameters
- **f** (FnMut(&mut [T]) -> usize) - A closure that takes a mutable slice of type `T` and returns the number of items written to the buffer. The slice provided to the closure contains garbage data on entry.

#### Returns
- **(usize, bool)** - A tuple where the first element is the number of items that can be written (free space), and the second element is `true` if the buffer was empty and data was written, `false` otherwise.

### `fn write_count(&self) -> usize`

#### Description
Returns the number of items that can currently be written to the buffer.

#### Returns
- **usize** - The number of items that can be written.
```

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

### Sender Methods

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/struct.Sender.html

Methods available on the Sender struct for sending data and managing buffer status.

```APIDOC
## fn send<F: FnMut(&mut [T]) -> (usize, bool)>(&mut self, f: F) -> Result<usize>

### Description
Writes data to the buffer using a closure. The closure receives a mutable slice of the buffer and returns the number of items written and a boolean indicating if the closure should be called again.

### Parameters
- **f** (FnMut(&mut [T]) -> (usize, bool)) - Required - A closure that writes data to the provided slice.

### Response
- **Result<usize>** - Returns the number of items that can be written to the buffer until it is full.

---

## fn wait_status(&self) -> (RawFd, usize)

### Description
Returns the file descriptor to wait for and the number of items that can be written. The file descriptor remains constant during the lifetime of the sender.

### Response
- **(RawFd, usize)** - A tuple containing the file descriptor and the available write capacity.

---

## fn wait_clear(&mut self) -> Result<()>

### Description
Clears the wait state. This should be called after being woken up by the wait file descriptor to prevent immediate re-triggering.

### Response
- **Result<()>** - Returns an empty result on success.
```

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

### Function fdringbuf::ringbuf::channel_bufsize

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel_bufsize.html

Utility function to determine the required buffer size for allocation.

```APIDOC
## Function fdringbuf::ringbuf::channel_bufsize

### Description
Use this utility function to figure out how big buffer you need to allocate.

### Method
N/A (This is a utility function, not an API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **usize** - The calculated buffer size.

#### Response Example
N/A
```

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

### fn fdringbuf::fdbuf::channel

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/fn.channel.html

Creates a channel with file descriptor signalling. This function does not take ownership of the provided file descriptors.

```APIDOC
## fn fdringbuf::fdbuf::channel

### Description
Creates a channel with fd signalling. Does not take ownership of the fds - they will not be closed when Sender and Receiver goes out of scope.

### Parameters
#### Arguments
- **slice** (&'a mut [u8]) - The buffer slice to be used by the channel.
- **empty** (Pipe) - The pipe used for signalling when the buffer is empty.
- **full** (Pipe) - The pipe used for signalling when the buffer is full.

### Returns
- **(Sender<'a, T>, Receiver<'a, T>)** - A tuple containing the Sender and Receiver halves of the channel.
```

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

### Receive Data with Callback

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/struct.Receiver.html

The recv method returns remaining items that can be read. The callback closure `f` determines how many items are written and if the operation should be repeated. It returns a Result with the number of items written.

```rust
fn recv<F:  FnMut(&[T]) -> (usize, bool)>(&mut self, f: F) -> Result<usize>
```

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

### fn recv

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/struct.Receiver.html

Consumes items from the buffer using a provided closure.

```APIDOC
## fn recv

### Description
Returns the number of remaining items and a boolean indicating if the buffer was full. The closure `f` determines how many items can be dropped from the buffer.

### Parameters
- **f** (FnMut(&[T]) -> usize) - Required - A closure that returns the number of items to drop from the buffer.

### Response
- **(usize, bool)** - A tuple containing the count of remaining items and a boolean indicating if the buffer was full.
```

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

### fdringbuf::channel_bufsize

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/index.html

Utility function to calculate the required buffer size for the ringbuffer.

```APIDOC
## fn channel_bufsize

### Description
Use this utility function to figure out how big a buffer you need to allocate for the ringbuffer.
```

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

### Move Up in Search Results

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel_bufsize.html

Press '⇤' (Tab key) to move up in the search results. This is a keyboard shortcut for navigating search results.

```text
⇤
```

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

### Define Pipe struct

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/struct.Pipe.html

Represents a pipe using two raw file descriptors.

```rust
pub struct Pipe {
    pub reader: RawFd,
    pub writer: RawFd,
}
```

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

### Calculate Channel Buffer Size

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel_bufsize.html

Use this utility function to determine the required buffer size for allocation based on capacity. It is a public function within the ringbuf module.

```rust
pub fn channel_bufsize<T: Copy>(capacity: usize) -> usize
```

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

### Receive Data from Ring Buffer

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/struct.Receiver.html

The recv method returns the number of remaining items and a boolean indicating if the buffer was full. The closure `f` determines how many items can be dropped from the buffer.

```rust
fn recv<F:  FnMut(&[T]) -> usize>(&mut self, f: F) -> (usize, bool)
```

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

### Send Data to Ring Buffer

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/struct.Sender.html

Sends data to the ring buffer using a closure that writes items. Returns the number of free items and a boolean indicating if the buffer was empty.

```rust
fn send<F:  FnMut(&mut [T]) -> usize>(&mut self, f: F) -> (usize, bool)
```

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

### Focus Search Field

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel_bufsize.html

Press 'S' to focus the search field. This is a keyboard shortcut for interacting with the search functionality.

```text
S
```

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

### Send Data to Buffer

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/struct.Sender.html

Sends data to the buffer using a closure. The closure receives a mutable slice and returns the number of items written and a boolean indicating if it should be called again. Returns the total number of items written.

```rust
fn send<F: FnMut(&mut [T]) -> (usize, bool)>(&mut self, f: F) -> Result<usize>
```

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

### Function fdringbuf::ringbuf::channel

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel.html

Creates a non-allocating channel using a pre-allocated buffer.

```APIDOC
## Function fdringbuf::ringbuf::channel

### Description
Create a channel (without signaling) Non-allocating - expects a pre-allocated buffer

### Method
N/A (This is a function signature, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **Sender<'a, T>** - The sender half of the channel.
- **Receiver<'a, T>** - The receiver half of the channel.

#### Response Example
N/A

```rust
pub fn channel<'a, T: Copy>(
    slice: &'a mut [u8]
) -> (Sender<'a, T>, Receiver<'a, T>)
```
```

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

### Go to Active Search Result

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel_bufsize.html

Press '⏎' (Enter key) to go to the active search result. This is a keyboard shortcut for selecting a search result.

```text
⏎
```

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

### fdringbuf::channel

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/index.html

Creates a new ringbuffer channel without signaling, requiring a pre-allocated buffer.

```APIDOC
## fn channel

### Description
Creates a channel (without signaling). This is a non-allocating function that expects a pre-allocated buffer.

### Parameters
- **buffer** (slice) - Required - A pre-allocated buffer to be used by the ringbuffer.
```

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

### Struct fdringbuf::fdbuf::Pipe

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/struct.Pipe.html

Represents a pipe with a reader and a writer, both of type RawFd.

```APIDOC
## Struct fdringbuf::fdbuf::Pipe

### Description
Represents a pipe with a reader and a writer.

### Fields
- **reader** (RawFd) - The file descriptor for reading from the pipe.
- **writer** (RawFd) - The file descriptor for writing to the pipe.

### Implementations
- **Debug**: Allows the struct to be formatted for debugging.
- **Copy**: Indicates that the struct can be copied by simply copying its bits.
- **Clone**: Provides a method to create a copy of the struct.
  - `fn clone(&self) -> Pipe`: Returns a copy of the value.
  - `fn clone_from(&mut self, source: &Self)`: Performs copy-assignment from `source`.
```

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

### Send Trait Implementation for Sender

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/struct.Sender.html

Implementation of the Send trait for the Sender struct.

```APIDOC
## Trait Implementations

### `impl<'a, T: Copy> Send for Sender<'a, T>`

#### Description
This block indicates that the `Sender` struct implements the `Send` trait, signifying that it is safe to transfer ownership of a `Sender` across threads.
```

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

### Move Down in Search Results

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/fn.channel_bufsize.html

Press '⇥' (Tab key) to move down in the search results. This is a keyboard shortcut for navigating search results.

```text
⇥
```

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

### fn read_count

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/struct.Receiver.html

Retrieves the number of items currently available to be read.

```APIDOC
## fn read_count

### Description
Returns the number of items that can be read from the buffer.

### Response
- **usize** - The number of items available for reading.
```

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

### Implement Send Trait

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/struct.Receiver.html

This snippet shows the implementation of the Send trait for the Receiver struct, indicating that Receiver instances can be safely sent across threads.

```rust
impl<'a, T:  Copy> Send for Receiver<'a, T>
```

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

### Clear Wait Status

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/struct.Receiver.html

The wait_clear method should be called after being woken up by the waitfd to prevent immediate re-awakening. Calling this when not woken by the waitfd may lead to a deadlock.

```rust
fn wait_clear(&mut self) -> Result<()>
```

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

### Struct fdringbuf::ringbuf::Sender

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/struct.Sender.html

Represents a sender for a ring buffer, allowing data to be written into it.

```APIDOC
## Struct fdringbuf::ringbuf::Sender

### Description
Represents a sender for a ring buffer, allowing data to be written into it.

### Fields
(fields omitted)
```

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

### Declare Sender Struct

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/ringbuf/struct.Sender.html

Defines the Sender struct for a ring buffer. It is generic over a lifetime 'a and a type T that must be Copy.

```rust
pub struct Sender<'a, T: 'a + Copy> { /* fields omitted */ }
```

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

### Define Receiver Struct

Source: https://docs.rs/fdringbuf/0.0.2/fdringbuf/fdbuf/struct.Receiver.html

Defines the Receiver struct, which is generic over a lifetime 'a and a type T that must be Copy. Fields are omitted in this declaration.

```rust
pub struct Receiver<'a, T: 'a + Copy> { /* fields omitted */ }
```
Tokens:
Raw