blob: 97a87ad63dee88165a849f808361e8e200f433cb [file] [log] [blame]
// Copyright 2016 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_TRAITS_H_
#define BASE_TASK_TASK_TRAITS_H_
#include <iosfwd>
#include <tuple>
#include <type_traits>
#include <utility>
#include "base/base_export.h"
#include "base/logging.h"
#include "base/task/task_traits_details.h"
#include "base/task/task_traits_extension.h"
#include "build/build_config.h"
#include "starboard/types.h"
namespace base {
// Valid priorities supported by the task scheduler. Note: internal algorithms
// depend on priorities being expressed as a continuous zero-based list from
// lowest to highest priority. Users of this API shouldn't otherwise care about
// nor use the underlying values.
enum class TaskPriority {
// This will always be equal to the lowest priority available.
LOWEST = 0,
// This task will only be scheduled when machine resources are available. Once
// running, it may be descheduled if higher priority work arrives (in this
// process or another) and its running on a non-critical thread.
BEST_EFFORT = LOWEST,
// This task affects UI or responsiveness of future user interactions. It is
// not an immediate response to a user interaction.
// Examples:
// - Updating the UI to reflect progress on a long task.
// - Loading data that might be shown in the UI after a future user
// interaction.
USER_VISIBLE,
// This task affects UI immediately after a user interaction.
// Example: Generating data shown in the UI immediately after a click.
USER_BLOCKING,
// This will always be equal to the highest priority available.
HIGHEST = USER_BLOCKING,
};
// Valid shutdown behaviors supported by the task scheduler.
enum class TaskShutdownBehavior {
// Tasks posted with this mode which have not started executing before
// shutdown is initiated will never run. Tasks with this mode running at
// shutdown will be ignored (the worker will not be joined).
//
// This option provides a nice way to post stuff you don't want blocking
// shutdown. For example, you might be doing a slow DNS lookup and if it's
// blocked on the OS, you may not want to stop shutdown, since the result
// doesn't really matter at that point.
//
// However, you need to be very careful what you do in your callback when you
// use this option. Since the thread will continue to run until the OS
// terminates the process, the app can be in the process of tearing down when
// you're running. This means any singletons or global objects you use may
// suddenly become invalid out from under you. For this reason, it's best to
// use this only for slow but simple operations like the DNS example.
CONTINUE_ON_SHUTDOWN,
// Tasks posted with this mode that have not started executing at
// shutdown will never run. However, any task that has already begun
// executing when shutdown is invoked will be allowed to continue and
// will block shutdown until completion.
//
// Note: Because TaskScheduler::Shutdown() may block while these tasks are
// executing, care must be taken to ensure that they do not block on the
// thread that called TaskScheduler::Shutdown(), as this may lead to deadlock.
SKIP_ON_SHUTDOWN,
// Tasks posted with this mode before shutdown is complete will block shutdown
// until they're executed. Generally, this should be used only to save
// critical user data.
//
// Note: Background threads will be promoted to normal threads at shutdown
// (i.e. TaskPriority::BEST_EFFORT + TaskShutdownBehavior::BLOCK_SHUTDOWN will
// resolve without a priority inversion).
BLOCK_SHUTDOWN,
};
// Tasks with this trait may block. This includes but is not limited to tasks
// that wait on synchronous file I/O operations: read or write a file from disk,
// interact with a pipe or a socket, rename or delete a file, enumerate files in
// a directory, etc. This trait isn't required for the mere use of locks. For
// tasks that block on base/ synchronization primitives, see the
// WithBaseSyncPrimitives trait.
struct MayBlock {};
// DEPRECATED. Use base::ScopedAllowBaseSyncPrimitives(ForTesting) instead.
//
// Tasks with this trait will pass base::AssertBaseSyncPrimitivesAllowed(), i.e.
// will be allowed on the following methods :
// - base::WaitableEvent::Wait
// - base::ConditionVariable::Wait
// - base::PlatformThread::Join
// - base::PlatformThread::Sleep
// - base::Process::WaitForExit
// - base::Process::WaitForExitWithTimeout
//
// Tasks should generally not use these methods.
//
// Instead of waiting on a WaitableEvent or a ConditionVariable, put the work
// that should happen after the wait in a callback and post that callback from
// where the WaitableEvent or ConditionVariable would have been signaled. If
// something needs to be scheduled after many tasks have executed, use
// base::BarrierClosure.
//
// On Windows, join processes asynchronously using base::win::ObjectWatcher.
//
// MayBlock() must be specified in conjunction with this trait if and only if
// removing usage of methods listed above in the labeled tasks would still
// result in tasks that may block (per MayBlock()'s definition).
//
// In doubt, consult with //base/task/OWNERS.
struct WithBaseSyncPrimitives {};
// Describes immutable metadata for a single task or a group of tasks.
class BASE_EXPORT TaskTraits {
private:
using TaskPriorityFilter =
trait_helpers::EnumTraitFilter<TaskPriority, TaskPriority::USER_VISIBLE>;
using MayBlockFilter = trait_helpers::BooleanTraitFilter<MayBlock>;
using TaskShutdownBehaviorFilter =
trait_helpers::EnumTraitFilter<TaskShutdownBehavior,
TaskShutdownBehavior::SKIP_ON_SHUTDOWN>;
using WithBaseSyncPrimitivesFilter =
trait_helpers::BooleanTraitFilter<WithBaseSyncPrimitives>;
public:
// ValidTrait ensures TaskTraits' constructor only accepts appropriate types.
struct ValidTrait {
ValidTrait(TaskPriority);
ValidTrait(TaskShutdownBehavior);
ValidTrait(MayBlock);
ValidTrait(WithBaseSyncPrimitives);
};
// Invoking this constructor without arguments produces TaskTraits that are
// appropriate for tasks that
// (1) don't block (ref. MayBlock() and WithBaseSyncPrimitives()),
// (2) prefer inheriting the current priority to specifying their own, and
// (3) can either block shutdown or be skipped on shutdown
// (TaskScheduler implementation is free to choose a fitting default).
//
// To get TaskTraits for tasks that require stricter guarantees and/or know
// the specific TaskPriority appropriate for them, provide arguments of type
// TaskPriority, TaskShutdownBehavior, MayBlock, and/or WithBaseSyncPrimitives
// in any order to the constructor.
//
// E.g.
// constexpr base::TaskTraits default_traits = {};
// constexpr base::TaskTraits user_visible_traits =
// {base::TaskPriority::USER_VISIBLE};
// constexpr base::TaskTraits user_visible_may_block_traits = {
// base::TaskPriority::USER_VISIBLE, base::MayBlock()};
// constexpr base::TaskTraits other_user_visible_may_block_traits = {
// base::MayBlock(), base ::TaskPriority::USER_VISIBLE};
template <class... ArgTypes,
#if __cplusplus < 201402L
class CheckArgumentsAreValid = trait_helpers::InitTypes<
decltype(ValidTrait(std::declval<ArgTypes>()))...>>
#else
class CheckArgumentsAreValid = std::enable_if_t<
trait_helpers::AreValidTraits<ValidTrait, ArgTypes...>::value ||
trait_helpers::AreValidTraitsForExtension<ArgTypes...>::value>>
#endif
constexpr TaskTraits(ArgTypes... args)
#if __cplusplus < 201402L
:
#else
: extension_(trait_helpers::GetTaskTraitsExtension(
trait_helpers::AreValidTraits<ValidTrait, ArgTypes...>{},
args...)),
#endif
priority_(
trait_helpers::GetTraitFromArgList<TaskPriorityFilter>(args...)),
shutdown_behavior_(
trait_helpers::GetTraitFromArgList<TaskShutdownBehaviorFilter>(
args...)),
priority_set_explicitly_(
trait_helpers::TraitIsDefined<TaskPriorityFilter>(args...)),
shutdown_behavior_set_explicitly_(
trait_helpers::TraitIsDefined<TaskShutdownBehaviorFilter>(args...)),
may_block_(trait_helpers::GetTraitFromArgList<MayBlockFilter>(args...)),
with_base_sync_primitives_(
trait_helpers::GetTraitFromArgList<WithBaseSyncPrimitivesFilter>(
args...)) {}
constexpr TaskTraits(const TaskTraits& other) = default;
TaskTraits& operator=(const TaskTraits& other) = default;
// TODO(eseckler): Default the comparison operator once C++20 arrives.
bool operator==(const TaskTraits& other) const {
static_assert(24 == sizeof(TaskTraits),
"Update comparison operator when TaskTraits change");
return extension_ == other.extension_ && priority_ == other.priority_ &&
shutdown_behavior_ == other.shutdown_behavior_ &&
priority_set_explicitly_ == other.priority_set_explicitly_ &&
shutdown_behavior_set_explicitly_ ==
other.shutdown_behavior_set_explicitly_ &&
may_block_ == other.may_block_ &&
with_base_sync_primitives_ == other.with_base_sync_primitives_;
}
// Returns TaskTraits constructed by combining |left| and |right|. If a trait
// is specified in both |left| and |right|, the returned TaskTraits will have
// the value from |right|. Note that extension traits are not merged: any
// extension traits in |left| are discarded if extension traits are present in
// |right|.
static constexpr TaskTraits Override(const TaskTraits& left,
const TaskTraits& right) {
return TaskTraits(left, right);
}
// Returns true if the priority was set explicitly.
constexpr bool priority_set_explicitly() const {
return priority_set_explicitly_;
}
// Returns the priority of tasks with these traits.
constexpr TaskPriority priority() const { return priority_; }
// Returns true if the shutdown behavior was set explicitly.
constexpr bool shutdown_behavior_set_explicitly() const {
return shutdown_behavior_set_explicitly_;
}
// Returns the shutdown behavior of tasks with these traits.
constexpr TaskShutdownBehavior shutdown_behavior() const {
return shutdown_behavior_;
}
// Returns true if tasks with these traits may block.
constexpr bool may_block() const { return may_block_; }
// Returns true if tasks with these traits may use base/ sync primitives.
constexpr bool with_base_sync_primitives() const {
return with_base_sync_primitives_;
}
uint8_t extension_id() const { return extension_.extension_id; }
// Access the extension data by parsing it into the provided extension type.
// See task_traits_extension.h for requirements on the extension type.
template <class TaskTraitsExtension>
const TaskTraitsExtension GetExtension() const {
DCHECK_EQ(TaskTraitsExtension::kExtensionId, extension_.extension_id);
return TaskTraitsExtension::Parse(extension_);
}
private:
constexpr TaskTraits(const TaskTraits& left, const TaskTraits& right)
: extension_(right.extension_.extension_id !=
TaskTraitsExtensionStorage::kInvalidExtensionId
? right.extension_
: left.extension_),
priority_(right.priority_set_explicitly_ ? right.priority_
: left.priority_),
shutdown_behavior_(right.shutdown_behavior_set_explicitly_
? right.shutdown_behavior_
: left.shutdown_behavior_),
priority_set_explicitly_(left.priority_set_explicitly_ ||
right.priority_set_explicitly_),
shutdown_behavior_set_explicitly_(
left.shutdown_behavior_set_explicitly_ ||
right.shutdown_behavior_set_explicitly_),
may_block_(left.may_block_ || right.may_block_),
with_base_sync_primitives_(left.with_base_sync_primitives_ ||
right.with_base_sync_primitives_) {}
// Ordered for packing.
TaskTraitsExtensionStorage extension_;
TaskPriority priority_;
TaskShutdownBehavior shutdown_behavior_;
bool priority_set_explicitly_;
bool shutdown_behavior_set_explicitly_;
bool may_block_;
bool with_base_sync_primitives_;
};
// Returns string literals for the enums defined in this file. These methods
// should only be used for tracing and debugging.
BASE_EXPORT const char* TaskPriorityToString(TaskPriority task_priority);
BASE_EXPORT const char* TaskShutdownBehaviorToString(
TaskShutdownBehavior task_priority);
// Stream operators so that the enums defined in this file can be used in
// DCHECK and EXPECT statements.
BASE_EXPORT std::ostream& operator<<(std::ostream& os,
const TaskPriority& shutdown_behavior);
BASE_EXPORT std::ostream& operator<<(
std::ostream& os,
const TaskShutdownBehavior& shutdown_behavior);
} // namespace base
#endif // BASE_TASK_TASK_TRAITS_H_