faux-folly/folly/ExecutorWithCancellation.h

/*
 * Copyright 2015 Nest Labs, Inc.
 *
 * 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/Executor.h>
#include <folly/Cancellation.h>

namespace folly {

/**
 * An Executor that has a single Cancellation associated with it
 *
 * This is a convenience interface for situations where you want an
 * event loop Executor that has a single Cancellation object
 * associated with it. When shutting down the Executor, the
 * Cancellation object can be used to cancel all pending transactions.
 */
class ExecutorWithCancellation : virtual public Executor {
public:
    /**
     * Replaces the Cancellation object, cancelling the current one.
     *
     * This should be called ONCE, before ever calling
     * getCancellation(). Before setting the new Cancellation, the
     * existing cancellation will be cancelled (thus cancelling all
     * in-flight transactions that referred to that Cancellation
     * object).
     *
     * @param cx the new Cancellation object for the Executor.
     */
    virtual void setCancellation(Cancellation cx) = 0;

    /**
     * Access the Cancellation object
     *
     * This allows the caller to access or create a copy of the
     * Cancellation object.
     *
     * @return the Cancellation object that is used to cancel all
     * transactions for this Executor.
     */
    virtual Cancellation& getCancellation() = 0;
};

} // folly