Struct Executor

pub struct Executor { /* private fields */ }

A collection of threads for executing tasks and blocking jobs.

The methods of this struct are defined on &Arc<Executor>.

Implementations

impl Executor

pub fn default() -> Arc<Executor>

Creates a new executor with 4 async threads and 4 blocking threads.

Panics

Panics when it fails to start the threads.

pub fn new( num_async_threads: usize, num_blocking_threads: usize, ) -> Result<Arc<Executor>, NewThreadPoolError>

Creates a new executor.

num_async_threads is the number of threads to use for executing async tasks.

num_blocking_threads is the number of threads to use for executing blocking jobs like connecting TCP sockets and reading files.

You probably want to use default instead of this.

Errors

Returns an error when a parameter is invalid or it fails to start threads.

pub fn with_name( async_threads_name: &'static str, num_async_threads: usize, blocking_threads_name: &'static str, num_blocking_threads: usize, ) -> Result<Arc<Executor>, NewThreadPoolError>

Creates a new executor with thread names prefixed with name.

For example, with_name("api_async", 4, "api_blocking", 100) creates 4 threads named "api_async0" through "api_async3" and 100 threads named "api_blocking0" through "api_blocking99".

Errors

Returns an error when a parameter is invalid or it fails to start threads.

pub fn schedule_blocking<T, F>(self: &Arc<Executor>, func: F) -> Receiver<T>

where T: Send + 'static, F: FnOnce() -> T + Send + 'static,

Schedules func to run on any available thread in the blocking thread pool.

Returns immediately.

Use the returned receiver to get the result of func. If func panics, the receiver returns RecvError.

Puts func in a Box before adding it to the thread pool queue.

pub fn spawn( self: &Arc<Executor>, fut: impl Future<Output = ()> + Send + 'static, )

Adds a task that will execute fut.

The task runs on any available worker thread. The task runs until fut completes or the Executor is dropped.

Returns immediately.

Uses std::boxed::Box::pin to make the future Unpin. You can use spawn_unpin to avoid this allocation.

Example:

let executor = safina_executor::Executor::default();
executor.spawn(async move {
    an_async_fn().await.unwrap();
});

pub fn spawn_unpin( self: &Arc<Executor>, fut: impl Future<Output = ()> + Send + Unpin + 'static, )

Adds a task that will execute fut.

The task runs on any available worker thread. The task runs until fut completes or the Executor is dropped.

Returns immediately.

Note that fut must be Unpin. You can use std::boxed::Box::pin to make it Unpin. The spawn function does this for you. Or use pin_utils::pin_mut to do it with unsafe code that does not allocate memory.

pub fn block_on<R>( self: &Arc<Executor>, fut: impl Future<Output = R> + 'static, ) -> R

Executes the future on the current thread and returns its result.

fut can call spawn to create tasks. Those tasks run on the executor and will continue even after fut completes and this call returns.

Uses std::boxed::Box::pin to make the future Unpin. You can use block_on_unpin to avoid this allocation.

Panics

Panics if the future panics.

Example

let executor = safina_executor::Executor::default();
let result = executor.block_on(async {
    prepare_request().await?;
    execute_request().await
})?;

pub fn block_on_unpin<R>( self: &Arc<Executor>, fut: impl Future<Output = R> + Unpin + 'static, ) -> R

Executes the future on the current thread and returns its result.

fut can call spawn to create tasks. Those tasks run on the executor and will continue even after fut completes and this call returns.

Note that fut must be Unpin. You can use std::boxed::Box::pin to make it Unpin. The block_on function does this for you. Or use pin_utils::pin_mut to do it with unsafe code that does not allocate memory.

Panics

Panics if the future panics.

Trait Implementations

impl Default for Executor

fn default() -> Executor

Returns the “default value” for a type.