#include <task_runner.hpp>

Inheritance diagram for fly::task::TaskRunner:

[legend]

Collaboration diagram for fly::task::TaskRunner:

Public Member Functions
virtual	~TaskRunner ()=default

template<typename TaskType >
bool	post_task (TaskLocation &&location, TaskType &&task)

template<typename OwnerType , typename TaskType >
bool	post_task (TaskLocation &&location, std::weak_ptr< OwnerType > weak_owner, TaskType &&task)

template<typename TaskType , typename ReplyType >
bool	post_task_with_reply (TaskLocation &&location, TaskType &&task, ReplyType &&reply)

template<typename OwnerType , typename TaskType , typename ReplyType >
bool	post_task_with_reply (TaskLocation &&location, std::weak_ptr< OwnerType > weak_owner, TaskType &&task, ReplyType &&reply)

template<typename TaskType >
bool	post_task_with_delay (TaskLocation &&location, std::chrono::milliseconds delay, TaskType &&task)

template<typename OwnerType , typename TaskType >
bool	post_task_with_delay (TaskLocation &&location, std::weak_ptr< OwnerType > weak_owner, std::chrono::milliseconds delay, TaskType &&task)

template<typename TaskType , typename ReplyType >
bool	post_task_with_delay_and_reply (TaskLocation &&location, std::chrono::milliseconds delay, TaskType &&task, ReplyType &&reply)

template<typename OwnerType , typename TaskType , typename ReplyType >
bool	post_task_with_delay_and_reply (TaskLocation &&location, std::weak_ptr< OwnerType > weak_owner, std::chrono::milliseconds delay, TaskType &&task, ReplyType &&reply)

Protected Member Functions
	TaskRunner (std::shared_ptr< TaskManager > task_manager) noexcept

virtual bool	post_task_internal (TaskLocation &&location, Task &&task)=0

virtual void	task_complete (TaskLocation &&location)=0

bool	post_task_to_task_manager (TaskLocation &&location, Task &&task)

bool	post_task_to_task_manager_with_delay (TaskLocation &&location, std::chrono::milliseconds delay, Task &&task)

Friends
class	TaskManager

Detailed Description

Base class for controlling the execution of tasks. Concrete task runners control the ordering and execution of tasks.

Tasks may generally be any callable type (lambda, std::function, etc.). Specific posting methods may place restrictions on the callable type, on either the return type of the invocation or the arguments the task accepts.

Tasks whose result is a non-void type may pass their result to a reply task. For example:

  auto task = []() -> int
  {
      // Task body here.
      return 12389;
  };

  auto reply = [](int task_result)
  {
      assert(task_result == 12389);
      // Reply body here.
  };

  task_runner->post_task_with_reply(FROM_HERE, std::move(task), std::move(reply));

Tasks whose result is void may indicate their completion to a reply task. For example:

  auto task = []()
  {
      // Task body here.
  };

  auto reply = []()
  {
      // Reply body here.
  };

  task_runner->post_task_with_reply(FROM_HERE, std::move(task), std::move(reply));

Mismatching of task result types and reply parameter types is explicitly forbidden at compile time. Tasks that return a non-void result must be paired with a reply which is invocable with only that type. Tasks which return void must be paired with a reply that is invocable without arguments.

Reply tasks are not executed immediately after a task is complete. Rather, they are posted for execution on the same task runner on which that task was posted.

Once a task is posted, it may be attempted to be cancelled in a number of ways:

Use one of the posting methods which accepts a weak pointer to the owner of the task. When the task is ready to be executed, if the weak pointer cannot be promoted to a strong pointer, the task is dropped. The task must accept a single argument, the shared pointer obtained from the weak pointer. For example:

auto task = [](std::shared_ptr<MyClass> self) { // Task body here. };

std::weak_ptr<MyClass> weak_self = shared_from_this(); task_runner->post_task(FROM_HERE, weak_self, std::move(task));

Reply tasks may be cancelled in the same manner. The reply task must then accept the result of the task and the shared pointer obtained from the weak pointer. If the task was dropped due to being unable to promote the weak pointer, the reply is also dropped. If the task was executed, when the reply is ready to be executed, if the weak pointer cannot be promoted to a strong pointer, the reply is dropped. For example:

auto task = [](std::shared_ptr<MyClass> self) -> int { // Task body here. return 12389; };

auto reply = [](int task_result, std::shared_ptr<MyClass> self) { assert(task_result == 12389); // Reply body here. };

std::weak_ptr<MyClass> weak_self = shared_from_this(); task_runner->post_task_with_reply(FROM_HERE, weak_self, std::move(task), std::move(reply));
Deleting the task runner onto which the task was posted. This will only cancel the task if the task manager has not yet instructed the task runner to execute the task.

Author: Timothy Flynn (trfly.nosp@m.nn89.nosp@m.@pm.m.nosp@m.e)

Version: August 12, 2018

Constructor & Destructor Documentation

◆ ~TaskRunner()

virtual fly::task::TaskRunner::~TaskRunner ( )

virtualdefault

Destructor.

◆ TaskRunner()

fly::task::TaskRunner::TaskRunner ( std::shared_ptr< TaskManager > task_manager )

protectednoexcept

Private constructor. Task runners may only be created by the task manager.

Parameters

task_manager The task manager.

Member Function Documentation

◆ post_task() [1/2]

template<typename OwnerType , typename TaskType >

bool fly::task::TaskRunner::post_task	(	TaskLocation &&	location,
		std::weak_ptr< OwnerType >	weak_owner,
		TaskType &&	task
	)

Post a task for execution with protection by the provided weak pointer. The task may be any callable type which accepts a single argument, a locked shared pointer obtained from the weak pointer. When the task is ready to be executed, if the weak pointer fails to be locked, the task is dropped.

Template Parameters

TaskType	Callable type of the task.
OwnerType	Type of the owner of the task.

Parameters

location	The location from which the task was posted (use FROM_HERE).
weak_owner	A weak pointer to the owner of the task.
task	The task to be executed.

Returns: True if the task was posted for execution.

◆ post_task() [2/2]

template<typename TaskType >

bool fly::task::TaskRunner::post_task	(	TaskLocation &&	location,
		TaskType &&	task
	)

Post a task for execution. The task may be any callable type.

Template Parameters

TaskType Callable type of the task.

Parameters

location	The location from which the task was posted (use FROM_HERE).
task	The task to be executed.

Returns: True if the task was posted for execution.

◆ post_task_internal()

virtual bool fly::task::TaskRunner::post_task_internal	(	TaskLocation &&	location,
		Task &&	task
	)

protectedpure virtual

Post a task for execution in accordance with the concrete task runner's policy.

Parameters

location	The location from which the task was posted.
task	The task to be executed.

Returns: True if the task was posted for execution.

Implemented in fly::task::SequencedTaskRunner, and fly::task::ParallelTaskRunner.

◆ post_task_to_task_manager()

bool fly::task::TaskRunner::post_task_to_task_manager	(	TaskLocation &&	location,
		Task &&	task
	)

protected

Forward a task to the task manager to be executed as soon as a worker thread is available.

Parameters

location	The location from which the task was posted.
task	The task to be executed.

Returns: True if the task was posted for execution.

◆ post_task_to_task_manager_with_delay()

bool fly::task::TaskRunner::post_task_to_task_manager_with_delay	(	TaskLocation &&	location,
		std::chrono::milliseconds	delay,
		Task &&	task
	)

protected

Forward a task to the task manager to be scheduled for excution after a delay. The task will be stored on the task manager's timer thread. Once the given delay has expired, the task will be handed back to the task runner to govern when the task will be posted from there.

Parameters

location	The location from which the task was posted.
delay	Delay before posting the task.
task	The task to be executed.

Returns: True if the task was posted for delayed execution.

◆ post_task_with_delay() [1/2]

template<typename TaskType >

bool fly::task::TaskRunner::post_task_with_delay	(	TaskLocation &&	location,
		std::chrono::milliseconds	delay,
		TaskType &&	task
	)

Schedule a task to be posted after a delay. The task may be any callable type.

Template Parameters

TaskType Callable type of the task.

Parameters

location	The location from which the task was posted (use FROM_HERE).
delay	Delay before posting the task.
task	The task to be executed.

Returns: True if the task was posted for delayed execution.

◆ post_task_with_delay() [2/2]

template<typename OwnerType , typename TaskType >

bool fly::task::TaskRunner::post_task_with_delay	(	TaskLocation &&	location,
		std::weak_ptr< OwnerType >	weak_owner,
		std::chrono::milliseconds	delay,
		TaskType &&	task
	)

Schedule a task to be posted after a delay with protection by the provided weak pointer. The task may be any callable type which accepts a single argument, a locked shared pointer obtained from the weak pointer. When the task is ready to be executed, if the weak pointer fails to be locked, the task is dropped.

Template Parameters

TaskType	Callable type of the task.
OwnerType	Type of the owner of the task.

Parameters

location	The location from which the task was posted (use FROM_HERE).
weak_owner	A weak pointer to the owner of the task.
delay	Delay before posting the task.
task	The task to be executed.

Returns: True if the task was posted for delayed execution.

◆ post_task_with_delay_and_reply() [1/2]

template<typename TaskType , typename ReplyType >

bool fly::task::TaskRunner::post_task_with_delay_and_reply	(	TaskLocation &&	location,
		std::chrono::milliseconds	delay,
		TaskType &&	task,
		ReplyType &&	reply
	)

Schedule a task to be posted after a delay. The task may be any callable type.

When the task has been executed, the reply task is then posted for execution on this same task runner. The reply task may be any callable type that is invocable with the return type of the task (if non-void), or without any arguments (if void).

Template Parameters

TaskType	Callable type of the task.
ReplyType	Callable type of the reply.

Parameters

location	The location from which the task was posted (use FROM_HERE).
delay	Delay before posting the task.
task	The task to be executed.
reply	The reply to be executed with the result of the task.

Returns: True if the task was posted for execution.

◆ post_task_with_delay_and_reply() [2/2]

template<typename OwnerType , typename TaskType , typename ReplyType >

bool fly::task::TaskRunner::post_task_with_delay_and_reply	(	TaskLocation &&	location,
		std::weak_ptr< OwnerType >	weak_owner,
		std::chrono::milliseconds	delay,
		TaskType &&	task,
		ReplyType &&	reply
	)

Schedule a task to be posted after a delay with protection by the provided weak pointer. The task may be any callable type which accepts a single argument, a locked shared pointer obtained from the weak pointer. When the task is ready to be executed, if the weak pointer fails to be locked, the task is dropped.

When the task has been executed, the reply task is then posted for execution on this same task runner with protection by the same weak pointer. The reply task may be any callable type that is invocable with the return type of the task (if non-void) and a locked shared pointer obtained from the weak pointer, or with only the locked shared pointer. When the reply is ready to be executed, if the weak pointer fails to be locked, the reply is dropped.

Template Parameters

TaskType	Callable type of the task.
ReplyType	Callable type of the reply.
OwnerType	Type of the owner of the task.

Parameters

location	The location from which the task was posted (use FROM_HERE).
weak_owner	A weak pointer to the owner of the task.
delay	Delay before posting the task.
task	The task to be executed.
reply	The reply to be executed with the result of the task.

Returns: True if the task was posted for execution.

◆ post_task_with_reply() [1/2]

template<typename OwnerType , typename TaskType , typename ReplyType >

bool fly::task::TaskRunner::post_task_with_reply	(	TaskLocation &&	location,
		std::weak_ptr< OwnerType >	weak_owner,
		TaskType &&	task,
		ReplyType &&	reply
	)

Post a task for execution with protection by the provided weak pointer. The task may be any callable type which accepts a single argument, a locked shared pointer obtained from the weak pointer. When the task is ready to be executed, if the weak pointer fails to be locked, the task is dropped.

When the task has been executed, the reply task is then posted for execution on this same task runner with protection by the same weak pointer. The reply task may be any callable type that is invocable with the return type of the task (if non-void) and a locked shared pointer obtained from the weak pointer, or with only the locked shared pointer. When the reply is ready to be executed, if the weak pointer fails to be locked, the reply is dropped.

Template Parameters

TaskType	Callable type of the task.
ReplyType	Callable type of the reply.
OwnerType	Type of the owner of the task.

Parameters

location	The location from which the task was posted (use FROM_HERE).
weak_owner	A weak pointer to the owner of the task.
task	The task to be executed.
reply	The reply to be executed with the result of the task.

Returns: True if the task was posted for execution.

◆ post_task_with_reply() [2/2]

template<typename TaskType , typename ReplyType >

bool fly::task::TaskRunner::post_task_with_reply	(	TaskLocation &&	location,
		TaskType &&	task,
		ReplyType &&	reply
	)

Post a task for execution. The task may be any callable type.

When the task has been executed, the reply task is then posted for execution on this same task runner. The reply task may be any callable type that is invocable with the return type of the task (if non-void), or without any arguments (if void).

Template Parameters

TaskType	Callable type of the task.
ReplyType	Callable type of the reply.

Parameters

location	The location from which the task was posted (use FROM_HERE).
task	The task to be executed.
reply	The reply to be executed with the result of the task.

Returns: True if the task was posted for execution.

◆ task_complete()

virtual void fly::task::TaskRunner::task_complete ( TaskLocation && location )

protectedpure virtual

Completion notification triggered by the task manager that a task has finished execution.

Parameters

location The location from which the task was posted.

Implemented in fly::task::SequencedTaskRunner, and fly::task::ParallelTaskRunner.

The documentation for this class was generated from the following files:

fly/task/task_runner.hpp
fly/task/task_runner.cpp

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~TaskRunner()

◆ TaskRunner()

Member Function Documentation

◆ post_task() [1/2]

◆ post_task() [2/2]

◆ post_task_internal()

◆ post_task_to_task_manager()

◆ post_task_to_task_manager_with_delay()

◆ post_task_with_delay() [1/2]

◆ post_task_with_delay() [2/2]

◆ post_task_with_delay_and_reply() [1/2]

◆ post_task_with_delay_and_reply() [2/2]

◆ post_task_with_reply() [1/2]

◆ post_task_with_reply() [2/2]

◆ task_complete()