async_patterns::TaskScope

#include <task_scope.h>

|TaskScope| lets you post asynchronous tasks that are silently discarded when the |TaskScope| object is destroyed.

Summary

In contrast, tasks posted using |async::PostTask|, |async::PostDelayedTask|, and so on will always run unless the dispatcher is shutdown there is no separate mechanism to cancel them.

The task scope is usually a member of some bigger async business logic object. By associating the lifetime of the posted async tasks with this object, one can conveniently capture or borrow other members from the async tasks without the need for reference counting to achieve memory safety. Example: 

class AsyncCounter {
 public:
  explicit AsyncCounter(async_dispatcher_t* dispatcher) : tasks_(dispatcher) {
    // Post some tasks to asynchronously count upwards.
    //
    // It is okay if |AsyncCounter| is destroyed before some of these tasks
    // come due. Those tasks will be discarded so they will not end up accessing
    // a destroyed object.
    tasks_.Post([this] { count_++ });
    tasks_.PostDelayed([this] { count_++ }, zx::sec(1));
    tasks_.PostDelayed(fit::bind_member<&AsyncCounter::CheckCount>(this), zx::sec(5));
  }

  void CheckCount() {
    assert(count_ == 2);
  }

 private:
  TaskScope tasks_;
  int count_ = 0;
};

|TaskScope| is thread-unsafe, and must be used and managed from a synchronized dispatcher.

Constructors and Destructors
TaskScope(async_dispatcher_t *dispatcher)
Creates a |TaskScope| that will post all tasks to the provided |dispatcher|.
~TaskScope()
Destroying the |TaskScope| synchronously destroys all pending tasks.

Public functions
Post(Closure && handler)
require_nullary_fn< Closure >
Schedules to invoke |handler| with a deadline of now.
PostDelayed(Closure && handler, zx::duration delay)
require_nullary_fn< Closure >
Schedules to invoke |handler| with a deadline expressed as a |delay| from now.
PostForTime(Closure && handler, zx::time deadline)
require_nullary_fn< Closure >
Schedules to invoke |handler| with the specified |deadline|.

Public functions

Post

require_nullary_fn< Closure > Post(
  Closure && handler
)

Schedules to invoke |handler| with a deadline of now.

|handler| should be a |void()| callable object.

The handler will not run if |TaskScope| is destroyed before it comes due. The handler will not run if the dispatcher shuts down before it comes due. In both cases, the handler will be synchronously destroyed during task scope destruction/dispatcher shutdown.

This is a drop-in replacement for |async::PostTask|.

PostDelayed

require_nullary_fn< Closure > PostDelayed(
  Closure && handler,
  zx::duration delay
)

Schedules to invoke |handler| with a deadline expressed as a |delay| from now.

|handler| should be a |void()| callable object.

The handler will not run if |TaskScope| is destroyed before it comes due. The handler will not run if the dispatcher shuts down before it comes due. In both cases, the handler will be synchronously destroyed during task scope destruction/dispatcher shutdown.

This is a drop-in replacement for |async::PostDelayedTask|.

PostForTime

require_nullary_fn< Closure > PostForTime(
  Closure && handler,
  zx::time deadline
)

Schedules to invoke |handler| with the specified |deadline|.

|handler| should be a |void()| callable object.

The handler will not run if |TaskScope| is destroyed before it comes due. The handler will not run if the dispatcher shuts down before it comes due. In both cases, the handler will be synchronously destroyed during task scope destruction/dispatcher shutdown.

This is a drop-in replacement for |async::PostTaskForTime|.

TaskScope

 TaskScope(
  async_dispatcher_t *dispatcher
)

Creates a |TaskScope| that will post all tasks to the provided |dispatcher|.

~TaskScope

 ~TaskScope()

Destroying the |TaskScope| synchronously destroys all pending tasks.

If a task attempts to reentrantly post more tasks into the |TaskScope| within its destructor, those tasks will be synchronously destroyed too.