callback_helpers.h | Explore in Territory

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

#ifndef MOJO_PUBLIC_CPP_BINDINGS_CALLBACK_HELPERS_H_
#define MOJO_PUBLIC_CPP_BINDINGS_CALLBACK_HELPERS_H_

#include <memory>
#include <utility>

#include "base/functional/bind.h"
#include "base/functional/callback.h"
#include "base/memory/ptr_util.h"

// This is a helper utility to wrap a base::OnceCallback such that if the
// callback is destructed before it has a chance to run (e.g. the callback is
// bound into a task and the task is dropped), it will be run with the
// default arguments passed into WrapCallbackWithDefaultInvokeIfNotRun.
// Alternatively, it will run the delete closure passed to
// WrapCallbackWithDropHandler.
//
// These helpers are intended for use on the client side of a mojo interface,
// where users want to know if their individual callback was dropped (e.g.
// due to connection error). This can save the burden of tracking pending
// mojo callbacks in a map so they can be cleaned up in the interface's
// connection error callback.
//
// Caveats:
// 1) The default form of the callback (the one called when the original is
//    dropped before running) will run on the thread where the callback's
//    destructor runs - it may not run on the thread you expected. If this is a
//    problem for your code, DO NOT USE these helpers. This is *not* a problem
//    for callbacks for mojo asynchronous methods, because in this case the
//    callback is run and destroyed on the same thread - the thread that
//    mojo::Remote is bound to.
// 2) There is no type information that indicates the wrapped object has special
//    destructor behavior.  It is therefore not recommended to pass these
//    wrapped callbacks into deep call graphs where code readers could be
//    confused whether or not the Run() method should be invoked.
//
// Example:
//   foo->DoWorkAndReturnResult(
//       WrapCallbackWithDefaultInvokeIfNotRun(
//           base::BindOnce(&Foo::OnResult, this), false));
//
// If the callback is destructed without running, it'll be run with "false".
//
//  foo->DoWorkAndReturnResult(
//      WrapCallbackWithDropHandler(base::BindOnce(&Foo::OnResult, this),
//                         base::BindOnce(&Foo::LogError, this, WAS_DROPPED)));

namespace mojo {
namespace internal {

// First, tell the compiler CallbackWithDeleteHelper is a class template with
// one type parameter. Then define specializations where the type is a function
// returning void and taking zero or more arguments.
template <typename Signature>
class CallbackWithDeleteHelper;

// Only support callbacks that return void because otherwise it is odd to call
// the callback in the destructor and drop the return value immediately.
CallbackWithDeleteHelper<void (Args...)>;

}  // namespace internal

template <typename T, typename... Args>
inline base::OnceCallback<T> WrapCallbackWithDropHandler(
    base::OnceCallback<T> cb,
    base::OnceClosure delete_cb) { … }

template <typename T, typename... Args>
inline base::OnceCallback<T> WrapCallbackWithDefaultInvokeIfNotRun(
    base::OnceCallback<T> cb,
    Args&&... args) { … }

}  // namespace mojo

#endif  // MOJO_PUBLIC_CPP_BINDINGS_CALLBACK_HELPERS_H_
chromium/mojo/public/cpp/bindings/callback_helpers.h
