Struct yaque::queue::Receiver

source ·
pub struct Receiver { /* private fields */ }
Expand description

The receiver part of the queue. This part is asynchronous and therefore needs an executor that will the poll the futures to completion.

Implementations§

source§

impl Receiver

source

pub fn open<P: AsRef<Path>>(base: P) -> Result<Receiver>

Opens a queue for reading. The access will be exclusive, based on the existence of the temporary file recv.lock inside the queue folder.

Errors

This function will return an IO error if the queue is already in use for receiving, which is indicated by a lock file. Also, any other IO error encountered while opening will be sent.

Panics

This function will panic if it is not able to set up the notification handler to watch for file changes.

source

pub fn save(&mut self) -> Result<()>

Saves the receiver queue state. You do not need to use method in most circumstances, since it is automatically done on drop (yes, it will be called eve if your thread panics). However, you can use this function to

  1. Make periodical backups. Use an external timer implementation for this.

  2. Handle possible IO errors in logging the state of the queue to the disk after commit. The drop implementation will ignore (but log) any io errors, which may lead to data loss in an unreliable filesystem. It was implemented this way because no errors are allowed to propagate on drop and panicking will abort the program if drop is called during a panic.

source

pub async fn recv(&mut self) -> Result<RecvGuard<'_, Vec<u8>>>

Retrieves an element from the queue. The returned value is a guard that will only commit state changes to the queue when dropped.

This operation is atomic. If the returned future is not polled to completion, as, e.g., when calling select, the operation will be undone.

Panics

This function will panic if it has to start reading a new segment and it is not able to set up the notification handler to watch for file changes.

source

pub fn try_recv(&mut self) -> Result<RecvGuard<'_, Vec<u8>>, TryRecvError>

Tries to retrieve an element from the queue. The returned value is a guard that will only commit state changes to the queue when dropped.

Panics

This function will panic if it has to start reading a new segment and it is not able to set up the notification handler to watch for file changes.

source

pub async fn recv_timeout<F>( &mut self, timeout: F ) -> Result<Option<RecvGuard<'_, Vec<u8>>>>where F: Future<Output = ()> + Unpin,

Retrieves an element from the queue until a given future finishes, whichever comes first. If an element arrives first, the returned value is a guard that will only commit state changes to the queue when dropped. Otherwise, Ok(None) is returned.

This operation is atomic. If the returned future is not polled to completion, as, e.g., when calling select, the operation will be undone.

Panics

This function will panic if it has to start reading a new segment and it is not able to set up the notification handler to watch for file changes.

source

pub async fn recv_batch( &mut self, n: usize ) -> Result<RecvGuard<'_, Vec<Vec<u8>>>>

Removes exactly ‘n’ elements from the queue. If there aren’t enough elements, it will wait until there are. Returns a guard that will only commit state changes to the queue when dropped.

Note

This operation is atomic in an asynchronous context. This means that you will not lose the elements if you do not await this function to completion.

Panics

This function will panic if it has to start reading a new segment and it is not able to set up the notification handler to watch for file changes.

source

pub async fn recv_batch_up_to( &mut self, n: usize ) -> Result<RecvGuard<'_, Vec<Vec<u8>>>>

Remove up to ‘n’ elements from the queue.

If the queue has data in it, this will immediately remove the first ‘n’ elements. If the queue is empty, it will await until there is some data to return, then return the first element.

The returned value is a guard that will only commit state changes to the queue when dropped.

Panics

This function will panic if it has to start reading a new segment and it is not able to set up the notification handler to watch for file changes.

source

pub fn try_recv_batch( &mut self, n: usize ) -> Result<RecvGuard<'_, Vec<Vec<u8>>>, TryRecvError>

Tries to remove a number of elements from the queue. The returned value is a guard that will only commit state changes to the queue when dropped.

Panics

This function will panic if it has to start reading a new segment and it is not able to set up the notification handler to watch for file changes.

source

pub fn try_recv_batch_up_to( &mut self, n: usize ) -> Result<RecvGuard<'_, Vec<Vec<u8>>>, TryRecvError>

Remove up to ‘n’ elements from the queue

If the queue has data in it, this will immediately remove the first ‘n’ elements. If the queue is empty, returns Err(TryRecvError::QueueEmpty).

The returned value is a guard that will only commit state changes to the queue when dropped.

Panics

This function will panic if it has to start reading a new segment and it is not able to set up the notification handler to watch for file changes.

source

pub async fn recv_batch_timeout<F>( &mut self, n: usize, timeout: F ) -> Result<RecvGuard<'_, Vec<Vec<u8>>>>where F: Future<Output = ()> + Unpin,

Tries to remove a number of elements from the queue until a given future finished. The values taken from the queue will be the values that were available during the whole execution of the future and thus less than n elements might be returned. The returned items are wrapped in a guard that will only commit state changes to the queue when dropped.

Note

This operation is atomic in an asynchronous context. This means that you will not lose the elements if you do not await this function to completion.

Panics

This function will panic if it has to start reading a new segment and it is not able to set up the notification handler to watch for file changes.

source

pub async fn recv_until<P, Fut>( &mut self, predicate: P ) -> Result<RecvGuard<'_, Vec<Vec<u8>>>>where P: FnMut(Option<&[u8]>) -> Fut, Fut: Future<Output = bool>,

Takes a number of elements from the queue until a certain asynchronous condition is met. Use this function if you want to have fine-grained control over the contents of the receive guard.

Note that the predicate function will receive a None as the first element. This allows you to return early and leave the queue intact. The returned value is a guard that will only commit state changes to the queue when dropped.

Note

This operation is atomic in an asynchronous context. This means that you will not lose the elements if you do not await this function to completion.

Example

Receive until an empty element is received:

let recv_guard = receiver.recv_until(|element| async { element.is_empty() }).await;
Panics

This function will panic if it has to start reading a new segment and it is not able to set up the notification handler to watch for file changes.

source

pub fn try_recv_until<P, Fut>( &mut self, predicate: P ) -> Result<RecvGuard<'_, Vec<Vec<u8>>>, TryRecvError>where P: FnMut(Option<&[u8]>) -> bool,

Tries to take a number of elements from the queue until a certain synchronous condition is met. Use this function if you want to have fine-grained control over the contents of the receive guard.

Note that the predicate function will receive a None as the first element. This allows you to return early and leave the queue intact. The returned value is a guard that will only commit state changes to the queue when dropped.

Example

Try to receive until an empty element is received:

let recv_guard = receiver.try_recv_until(|element| element.is_empty());
Panics

This function will panic if it has to start reading a new segment and it is not able to set up the notification handler to watch for file changes.

Trait Implementations§

source§

impl Drop for Receiver

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

fn vzip(self) -> V