base/task/task_scheduler/task_source.h

// Copyright 2019 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef BASE_TASK_TASK_SCHEDULER_TASK_SOURCE_H_
#define BASE_TASK_TASK_SCHEDULER_TASK_SOURCE_H_

#include <stddef.h>

#include "base/base_export.h"
#include "base/macros.h"
#include "base/memory/ref_counted.h"
#include "base/optional.h"
#include "base/task/common/intrusive_heap.h"
#include "base/task/task_scheduler/scheduler_lock.h"
#include "base/task/task_scheduler/sequence_sort_key.h"
#include "base/task/task_scheduler/task.h"
#include "base/task/task_traits.h"

namespace base {
namespace internal {

// A TaskSource is a virtual class that provides a series of Tasks that must be
// executed.
//
// In order to execute a task from this TaskSource, a worker should first make
// sure that it can take up an additional worker with NeedsWorker(). TakeTask()
// can then be called to access the next Task, and Pop() must be called after
// the task executed and before accessing any subsequent Tasks. This ensure that
// the number of workers concurrently running tasks never go over the intended
// concurrency.
//
// In comments below, an "empty TaskSource" is a TaskSource with no Task.
//
// Note: there is a known refcounted-ownership cycle in the Scheduler
// architecture: TaskSource -> Task -> TaskRunner -> TaskSource -> ...
// This is okay so long as the other owners of TaskSource (PriorityQueue and
// SchedulerWorker in alternation and
// SchedulerWorkerPoolImpl::SchedulerWorkerDelegateImpl::GetWork()
// temporarily) keep running it (and taking Tasks from it as a result). A
// dangling reference cycle would only occur should they release their reference
// to it while it's not empty. In other words, it is only correct for them to
// release it after IsEmpty() returns true.
// TODO(etiennep): Break ownership cycle by moving TaskRunner reference from
// Task to TaskSource.
//