folly/folly/CancellationToken.h

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#pragma once

#include <folly/CppAttributes.h>
#include <folly/Function.h>

#include <atomic>
#include <memory>
#include <thread>
#include <type_traits>

namespace folly {

class CancellationCallback;
class CancellationSource;
struct OperationCancelled : public std::exception { … };

namespace detail {
class CancellationState;
struct CancellationStateTokenDeleter { … };
struct CancellationStateSourceDeleter { … };
CancellationStateTokenPtr;
CancellationStateSourcePtr;
template <typename...>
struct WithDataTag;
} // namespace detail

/**
 * A CancellationToken is an object that can be passed into an function or
 * operation that allows the caller to later request that the operation be
 * cancelled.
 *
 * A CancellationToken object can be obtained by calling the .getToken()
 * method on a CancellationSource or by copying another CancellationToken
 * object. All CancellationToken objects obtained from the same original
 * CancellationSource object all reference the same underlying cancellation
 * state and will all be cancelled together.
 *
 * If your function needs to be cancellable but does not need to request
 * cancellation then you should take a CancellationToken as a parameter.
 * If your function needs to be able to request cancellation then you
 * should instead take a CancellationSource as a parameter.
 *
 * @refcode folly/docs/examples/folly/CancellationToken.cpp
 * @class folly::CancellationToken
 */
class CancellationToken { … };

bool operator==(
    const CancellationToken& a, const CancellationToken& b) noexcept;
bool operator!=(
    const CancellationToken& a, const CancellationToken& b) noexcept;

/**
 * A CancellationSource object provides the ability to request cancellation of
 * operations that an associated CancellationToken was passed to.
 *
 * @refcode folly/docs/examples/folly/CancellationSource.cpp
 * @class folly::CancellationSource
 */
// Example usage:
//   CancellationSource cs;
//   Future<void> f = startSomeOperation(cs.getToken());
//
//   // Later...
//   cs.requestCancellation();
class CancellationSource { … };

bool operator==(
    const CancellationSource& a, const CancellationSource& b) noexcept;
bool operator!=(
    const CancellationSource& a, const CancellationSource& b) noexcept;

/**
 * A CancellationCallback object registers the callback with the specified
 * CancellationToken such that the callback will be
 * executed if the corresponding CancellationSource object has the
 * requestCancellation() method called on it.
 *
 * If the CancellationToken object already had cancellation requested
 * then the callback will be executed inline on the current thread before
 * the constructor returns. Otherwise, the callback will be executed on
 * in the execution context of the first thread to call requestCancellation()
 * on a corresponding CancellationSource.
 *
 * The callback object must not throw any unhandled exceptions. Doing so
 * will result in the program terminating via std::terminate().
 *
 * A CancellationCallback object is neither copyable nor movable.
 *
 * @refcode folly/docs/examples/folly/CancellationCallback.cpp
 * @class folly::CancellationCallback
 */
class CancellationCallback { … };

} // namespace folly

#include <folly/CancellationToken-inl.h>