Mercury Currency Engine
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
mce::scheduler Struct Reference

object responsible for scheduling and executing coroutines More...

#include <scheduler.hpp>

Inheritance diagram for mce::scheduler:
Inheritance graph
[legend]
Collaboration diagram for mce::scheduler:
Collaboration graph
[legend]

Classes

struct  measurement
 a struct allowing comparison of scheduler workload More...
 
struct  park
 fundamental structure for allowing blocking of coroutines running on a scheduler More...
 
struct  parkable
 object containing information to block and unblock a coroutine (running in a scheduler) or thread More...
 
struct  parkable_notify
 

Public Types

typedef mce::detail::queue< parkable * > parkable_queue
 most straightforward blocked queue
 
typedef mce::detail::queue< parkable_notifyparkable_notify_queue
 blocked queue for parkable_notify structs
 
- Public Types inherited from mce::lifecycle
enum  state { ready , running , suspended , halted }
 an enumeration which represents the lifecycle object's current state More...
 

Public Member Functions

bool run ()
 
template<typename A , typename... As>
void schedule (A &&a, As &&... as)
 schedule allocated coroutine(s) More...
 
measurement measure ()
 
 operator std::shared_ptr< scheduler > ()
 return a copy of this scheduler's shared pointer by conversion
 
- Public Member Functions inherited from mce::lifecycle
 lifecycle (implementation *self)
 
 lifecycle (implementation *self, implementation *root)
 
state get_state ()
 return the state of the lifecycle
 
bool suspend ()
 temporarily suspend operations More...
 
void resume ()
 resume any current or future call to run() after an suspend()
 
void halt ()
 halt and join lifecycle execution More...
 

Static Public Member Functions

static std::shared_ptr< schedulermake (lifecycle::implementation *root=nullptr)
 return an allocated and initialized scheduler
 

Protected Member Functions

state get_state_impl ()
 
bool suspend_impl ()
 
void resume_impl ()
 
void halt_impl ()
 

Detailed Description

object responsible for scheduling and executing coroutines

mce::scheduler cannot be created directly, it must be created by calling mce::scheduler::make()

Scheduler API, unless otherwise specified, is threadsafe and coroutine-safe. That is, it can be called from anywhere safely, including from within a coroutine running on the scheduler which is being accessed.

Member Function Documentation

◆ measure()

measurement mce::scheduler::measure ( )
inline

The returned value is a best-effort attempt to represent the scheduler's current scheduling load.

The returned value is useful for finding the lowest scheduling load among multiple schedulers, it can be directly compared using < operator.

Returns
a value representing the current scheduling load

◆ run()

bool mce::scheduler::run ( )
inline
 @brief run the scheduler, continuously executing coroutines

 This procedure can only be called by one caller at a time, and will block 
 the caller until `suspend()` or `halt()` is called. 

 Execution of coroutines by the caller of `run()` can be paused by calling 
 `suspend()`, causing `run()` to return `true`. Further calls to `run()` 
 will block until `resume()` is called.

 If `halt()` was previously called or `run()` is already evaluating 
 somewhere else will immediately return `false`.

 A simple usage of this feature is calling `run()` in a loop:
 ```
 while(my_scheduler->run()) 
 { 

do other things after suspend() }

do other things after halt() ```

Doing so allows coroutine execution on this scheduler to be "put to sleep" until resume() is called elsewhere. IE, this blocks the entire scheduler, and all coroutines scheduled on it, until resume() is called.

This function is heavily optimized as it is a processing bottleneck.

Returns
true if run() was suspended by suspend(), else false

◆ schedule()

template<typename A , typename... As>
void mce::scheduler::schedule ( A &&  a,
As &&...  as 
)
inline

schedule allocated coroutine(s)

Arguments to this function can be:

After the above argument types, any remaining arguments can be:

  • a Callable (followed by any arguments for the Callable)

The user can manually construct allocated std::unique_ptr<mce::coroutine>s with mce::coroutine::make()

Multi-argument schedule()s hold the scheduler's lock throughout (they are simultaneously scheduled). This allows runtime order guarantees.

Parameters
athe first argument
asany remaining arguments

The documentation for this struct was generated from the following file: