Struct juggle::WheelHandle

pub struct WheelHandle<'futures> { /* fields omitted */ }

Handle used to spawn and control tasks in assigned Wheel. All tasks manipulation are done by this struct.

Implementations

impl<'futures> WheelHandle<'futures>

pub fn is_valid(&self) -> bool

Checks if this handle is valid. Handles are weak references bound to specific Wheel.

This method returns true if specific handle is valid. If handle is valid it means that it can be used to control tasks in Wheel associated with it. Handle is valid until associated wheel is dropped or locked.

Examples

use juggle::*;
let wheel = Wheel::new();
let handle = wheel.handle().clone();

assert!(handle.is_valid()); // Ok, useful handle.
drop(wheel);
assert!(!handle.is_valid()); // Handle can no longer be used to control Wheel.

pub fn is_same(&self, other: &WheelHandle<'_>) -> bool

Checks if this and other handle reference the same Wheel.

Examples

use juggle::*;
let wheel = Wheel::new();
let wheel2 = Wheel::new();

let h1 = wheel.handle();
let h2 = h1.clone();
let other = wheel2.handle();

assert!(h1.is_same(&h2));
assert!(!h1.is_same(&other));

pub fn spawn_default<F>(&self, future: F) -> Option<IdNum> where
    F: Future<Output = ()> + 'futures, 

Create new task and obtain its id, equivalent to: spawn(SpawnParams::default(), future).

Arguments

• future - The future you want to schedule.

Allocates new task inside associated Wheel. Returns identifier of newly allocated task or None if this handle is invalid.

pub fn spawn<P, F>(&self, params: P, future: F) -> Option<IdNum> where
    F: Future<Output = ()> + 'futures,
    P: Into<SpawnParams>, 

Create new task and obtain its id.

Arguments

• params - Task creation parameters. Using default will spawn runnable task without name.
• future - The future you want to schedule.

Allocates new task inside associated Wheel. You can specify creation parameters of this task. Returns identifier of newly allocated task or None if this handle is invalid.

pub fn spawn_dyn<P>(
    &self,
    params: P,
    future: Pin<Box<dyn Future<Output = ()> + 'futures>>
) -> Option<IdNum> where
    P: Into<SpawnParams>, 

Create new task from boxed future and obtain its id.

Arguments

• params - Task creation parameters. Using default will spawn runnable task without name.
• future - Boxed future you want to schedule.

Allocates new task inside associated Wheel. You can specify creation parameters of this task. Returns identifier of newly allocated task or None if this handle is invalid.

pub fn cancel(&self, id: IdNum) -> bool

Cancel task with given id.

If task is already executing then it will become cancelled when next yield occurs. Note that when getting state of this cancelled task it might be Cancelled for some time but eventually it will become Unknown because scheduler removes tasks only after circling through all runnable tasks. Then when new task is spawned it might be assigned to the same id.

pub fn suspend(&self, id: IdNum) -> bool

Suspend task with given id.

Suspended tasks cannot execute until resumed. After this operation the task will change state to Suspended. Returns true if task was successfully suspended and false if it can't be suspended for any reason (e.g it was already suspended, cancelled or handle is invalid).

pub fn resume(&self, id: IdNum) -> bool

Resume task with given id.

After this operation given task can be executed again. It will change state to Runnable or Waiting in case it still waits for some external event. Returns true if task was successfully resumed, and false if it wasn't suspended or handle is invalid.

pub fn get_state(&self, id: IdNum) -> State

Get state of task with given id.

If this handle is invalid then returns State::Unknown. For more information about allowed states see State.

Examples

use juggle::*;

let wheel = Wheel::new();
let id1 = wheel.handle().spawn(SpawnParams::default(),async {/*...*/}).unwrap();
let id2 = wheel.handle().spawn(SpawnParams::suspended(true),async {/*...*/}).unwrap();

assert_eq!(wheel.handle().get_state(id1),State::Runnable);
assert_eq!(wheel.handle().get_state(id2),State::Suspended);

pub fn current(&self) -> Option<IdNum>

Get id of currently executing task.

Returns None when:

• Not called inside task.
• Handle is invalid.

Examples

use juggle::*;

async fn self_cancelling_task(handle: WheelHandle<'_>){
    let id = handle.current().unwrap();
    handle.cancel(id);
    yield_once!(); // give control to scheduler

    unreachable!("This line will never be reached.");
}

let wheel = Wheel::new();
let handle = wheel.handle();
handle.spawn(SpawnParams::default(), self_cancelling_task(handle.clone())).unwrap();
smol::block_on(wheel).unwrap();

pub fn with_name<F, T>(&self, id: IdNum, func: F) -> T where
    F: FnOnce(Option<&str>) -> T, 

Applies given function on reference to given task name and returns result of that function.

The argument that is passed to func is None when:

• Task is unnamed.
• Given id is not assigned to any task.
• Handle is invalid.

Examples

use juggle::*;

let wheel = Wheel::new();
let bark = wheel.handle().spawn(SpawnParams::named("Dog"), async {/*...*/}).unwrap();
let meow = wheel.handle().spawn(SpawnParams::named("Cat"), async {/*...*/}).unwrap();
let none = wheel.handle().spawn(SpawnParams::default(), async {/*...*/}).unwrap();

assert!(wheel.handle().with_name(bark, |name| name == Some("Dog")));
assert!(wheel.handle().with_name(meow, |name| name == Some("Cat")));
assert!(wheel.handle().with_name(none, |name| name == None));

pub fn get_current_name(&self) -> Option<Cow<'static, str>>

Returns name of current task.

Returns None when:

• Task is unnamed.
• Not called inside task.
• Handle is invalid.

Note that if current task was named with static lifetime string, it will be returned from this method as Cow::Borrowed. When task has dynamic name then Cow::Owned is returned with fresh allocated String of that name. If you don't want to allocate temporary memory for string use in such case, use with_name.

pub fn get_name(&self, id: IdNum) -> Option<Cow<'static, str>>

Returns name of task with given id. Returns None when:

• Task is unnamed.
• Given id is not assigned to any task.
• Handle is invalid.

Note that if specified task was named with static lifetime string, it will be returned from this method as Cow::Borrowed. When task has dynamic name then Cow::Owned is returned with fresh allocated String of that name. If you don't want to allocate temporary memory for string use in such case, use with_name.

pub fn get_by_name(&self, name: &str) -> Option<IdNum>

Find task id that has name equal to given argument.

Returns None when:

• Task was not found.
• Handle is invalid.

pub fn registered_count(&self) -> usize

Returns number of total registered tasks in this scheduler at the moment or 0 if this handle is invalid.

Trait Implementations

impl<'futures> Clone for WheelHandle<'futures>

fn clone(&self) -> WheelHandle<'futures>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'futures> Debug for WheelHandle<'futures>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'futures> Eq for WheelHandle<'futures>

impl<'futures> Hash for WheelHandle<'futures>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<'futures> PartialEq<WheelHandle<'futures>> for WheelHandle<'futures>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.