Struct safina::Executor

pub struct Executor { /* fields omitted */ }

A collection of threads for executing tasks and blocking jobs.

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

Implementations

impl Executor

#[must_use]pub fn default() -> Arc<Executor>

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

#[must_use]pub fn new(
    num_async_threads: usize,
    num_blocking_threads: usize
) -> Arc<Executor>

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.

#[must_use]pub fn with_name(
    async_threads_name: &'static str,
    num_async_threads: usize,
    blocking_threads_name: &'static str,
    num_blocking_threads: usize
) -> Arc<Executor>

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".

pub fn schedule_blocking<T>(
    self: &Arc<Executor>,
    f: impl FnOnce() -> T + Send + 'static
) -> Promise<T> where
    T: 'static + Send, 

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

Returns immediately.

Await the returned promise to get the result of f. If f panics, the promise will never complete.

Puts f 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> + Send + '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> + Send + 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

pub fn default() -> Executor

Returns the “default value” for a type.