SeqLock

https://docs.rs/seqlock/0.2.0/seqlock/
Admin
SeqLock is a Rust library providing a reader-writer lock heavily optimized for readers, offering up...
Tokens:1,424
Snippets:15
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### SeqLock Usage Example

Source: https://docs.rs/seqlock

Demonstrates how to initialize, write to, and read from a SeqLock.

```APIDOC
## SeqLock Usage Example

This example shows the basic usage of the `SeqLock` for both writing and reading.

### Method

N/A (Illustrative Example)

### Endpoint

N/A (Illustrative Example)

### Parameters

N/A

### Request Example

```rust
use seqlock::SeqLock;

let lock = SeqLock::new(5);

// Writing to the data involves a lock
{
    let mut w = lock.lock_write();
    *w += 1;
    assert_eq!(*w, 6);
}

// Reading the data is a very fast operation
{
    let r = lock.read();
    assert_eq!(r, 6);
}
```

### Response

N/A (Illustrative Example)
```

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

### Basic SeqLock Usage

Source: https://docs.rs/seqlock

Demonstrates the fundamental usage of SeqLock for both writing and reading. Writing requires a mutable lock, while reading is a fast, non-blocking operation. Ensure the data type implements the Copy trait.

```rust
use seqlock::SeqLock;

let lock = SeqLock::new(5);

{
    // Writing to the data involves a lock
    let mut w = lock.lock_write();
    *w += 1;
    assert_eq!(*w, 6);
}

{
    // Reading the data is a very fast operation
    let r = lock.read();
    assert_eq!(r, 6);
}
```

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

### SeqLock Implementation Details

Source: https://docs.rs/seqlock/0.2.0/seqlock/index.html

Explains the underlying mechanism of SeqLock based on a sequence counter.

```APIDOC
## SeqLock Implementation

### Description
The `SeqLock` implementation is based on the Linux seqlock type. It uses a sequence counter to manage data consistency between readers and writers.

### Reader Operation
1. Read the sequence counter.
2. Read the data.
3. Read the sequence counter again.
4. If the sequence counter values differ, retry.
5. Otherwise, the read data is consistent.

### Writer Operation
1. Increment the sequence counter.
2. Write to the data.
3. Increment the sequence counter again.

### Method
N/A (Conceptual explanation)

### Endpoint
N/A

### Parameters
N/A

### Request Body
N/A

### Response
N/A
```

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

### SeqLock Methods

Source: https://docs.rs/seqlock/0.2.0/seqlock/struct.SeqLock.html

Methods for creating, reading, and writing to a SeqLock instance.

```APIDOC
## new(val: T)

### Description
Creates a new SeqLock with the given initial value.

### Method
Constructor

## read()

### Description
Reads the value protected by the SeqLock. This operation is extremely fast as it allows multiple readers to read without interference. If a writer is active, the thread will block.

### Method
GET

## lock_write()

### Description
Locks the SeqLock with exclusive write access, blocking the current thread until acquired. Does not block concurrent readers.

### Method
POST

## try_lock_write()

### Description
Attempts to lock the SeqLock with exclusive write access without blocking. Returns None if the lock cannot be acquired.

### Method
POST

## into_inner()

### Description
Consumes the SeqLock and returns the underlying data.

### Method
POST

## get_mut()

### Description
Returns a mutable reference to the underlying data, bypassing the need for locking.

### Method
GET
```

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

### SeqLockGuard Struct

Source: https://docs.rs/seqlock

Information about the SeqLockGuard struct.

```APIDOC
## Struct: SeqLockGuard

### Description
RAII structure used to release the exclusive write access of a `SeqLock` when dropped.

### Methods

- **deref** (&self) -> &T
  Returns an immutable reference to the protected data.
- **deref_mut** (&mut self) -> &mut T
  Returns a mutable reference to the protected data.
```

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

### SeqLock Struct

Source: https://docs.rs/seqlock

Information about the SeqLock struct.

```APIDOC
## Struct: SeqLock

### Description
A sequential lock.

### Fields

- **data** (T) - The data protected by the lock. Must implement `Copy`.
- **sequence** (u32) - The sequence counter used to track modifications.
```

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

### Define SeqLock struct

Source: https://docs.rs/seqlock/0.2.0/seqlock/struct.SeqLock.html

The definition of the SeqLock structure.

```rust
pub struct SeqLock<T> { /* private fields */ }
```

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

### SeqLockGuard Struct

Source: https://docs.rs/seqlock/0.2.0/seqlock/struct.SeqLockGuard.html

The SeqLockGuard is an RAII structure that ensures the exclusive write access of a SeqLock is released when the guard is dropped.

```APIDOC
## Struct SeqLockGuard

RAII structure used to release the exclusive write access of a `SeqLock` when dropped.

```rust
pub struct SeqLockGuard<'a, T> { /* private fields */ }
```
```

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

### Drop Trait Implementation for SeqLockGuard

Source: https://docs.rs/seqlock/0.2.0/seqlock/struct.SeqLockGuard.html

Defines the behavior when the SeqLockGuard goes out of scope, releasing the lock.

```APIDOC
### impl<T> Drop for SeqLockGuard<'_, T>

#### fn drop(&mut self)

Executes the destructor for this type.
```

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

### Deref Trait Implementation for SeqLockGuard

Source: https://docs.rs/seqlock/0.2.0/seqlock/struct.SeqLockGuard.html

Allows dereferencing SeqLockGuard to access the underlying data.

```APIDOC
### impl<'a, T: Copy + 'a> Deref for SeqLockGuard<'a, T>

#### type Target = T

The resulting type after dereferencing.

#### fn deref(&self) -> &T

Dereferences the value.
```

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

### DerefMut Trait Implementation for SeqLockGuard

Source: https://docs.rs/seqlock/0.2.0/seqlock/struct.SeqLockGuard.html

Allows mutable dereferencing of SeqLockGuard to modify the underlying data.

```APIDOC
### impl<'a, T: Copy + 'a> DerefMut for SeqLockGuard<'a, T>

#### fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.
```
Tokens:
Raw