ppapi/c/pp_completion_callback.h

/* Copyright (c) 2012 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.
 */

/* From pp_completion_callback.idl modified Thu May  9 14:59:57 2013. */

#ifndef PPAPI_C_PP_COMPLETION_CALLBACK_H_
#define PPAPI_C_PP_COMPLETION_CALLBACK_H_

#include "ppapi/c/pp_macros.h"
#include "ppapi/c/pp_stdint.h"

/**
 * @file
 * This file defines the API to create and run a callback.
 */


/**
 * @addtogroup Typedefs
 * @{
 */
/**
 * This typedef defines the signature that you implement to receive callbacks
 * on asynchronous completion of an operation.
 *
 * @param[in] user_data A pointer to user data passed to a callback function.
 * @param[in] result If result is 0 (PP_OK), the operation succeeded.  Negative
 * values (other than -1 or PP_OK_COMPLETE) indicate error and are specified
 * in pp_errors.h. Positive values for result usually indicate success and have
 * some operation-dependent meaning (such as bytes read).
 */
typedef void (*PP_CompletionCallback_Func)(void* user_data, int32_t result);
/**
 * @}
 */

/**
 * @addtogroup Enums
 * @{
 */
/**
 * This enumeration contains flags used to control how non-NULL callbacks are
 * scheduled by asynchronous methods.
 */
typedef enum {
  /**
   * By default any non-NULL callback will always invoked asynchronously,
   * on success or error, even if the operation could complete synchronously
   * without blocking.
   *
   * The method taking such callback will always return PP_OK_COMPLETIONPENDING.
   * The callback will be invoked on the same thread on which the method was
   * invoked.
   *
   * NOTE: If the method taking the callback is invoked on a background
   * thread that has no valid PPB_MessageLoop resource attached, the system has
   * no way to run the callback on the correct thread. In this case, a log
   * message will be emitted and the plugin will be made to crash.
   */
  PP_COMPLETIONCALLBACK_FLAG_NONE = 0 << 0,
  /**
   * This flag allows any method taking such callback to complete synchronously
   * and not call the callback if the operation would not block. This is useful
   * when performance is an issue, and the operation bandwidth should not be
   * limited to the processing speed of the message loop.
   *
   * On synchronous method completion, the completion result will be returned
   * by the method itself. Otherwise, the method will return
   * PP_OK_COMPLETIONPENDING, and the callback will be invoked asynchronously on
   * the same thread on which the method was invoked. If there is no valid
   * PPB_MessageLoop attached to that thread, and the callback would normally
   * run asynchronously, the invoked method will return
   * PP_ERROR_NO_MESSAGE_LOOP.
   */
  PP_COMPLETIONCALLBACK_FLAG_OPTIONAL = 1 << 0
} PP_CompletionCallback_Flag;
PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_CompletionCallback_Flag, 4);
/**
 * @}
 */

/**
 * @addtogroup Structs
 * @{
 */
/**
 * <code>PP_CompletionCallback</code> is a common mechanism for supporting
 * potentially asynchronous calls in browser interfaces. Any method that takes a
 * <code>PP_CompletionCallback</code> can be used in one of three different
 * ways:
 *   - Required: The callback will always be invoked asynchronously on the
 *               thread where the associated PPB method was invoked. The method
 *               will always return PP_OK_COMPLETIONPENDING when a required
 *               callback, and the callback will be invoked later (barring
 *               system or thread shutdown; see PPB_MessageLoop for details).
 *               Required callbacks are the default.
 *               <br /><br />
 *               NOTE: If you use a required callback on a background thread,
 *               you must have created and attached a PPB_MessageLoop.
 *               Otherwise, the system can not run your callback on that thread,
 *               and will instead emit a log message and crash your plugin to
 *               make the problem more obvious.
 *
 *   - Optional: The callback may be invoked asynchronously, or the PPB method
 *               may complete synchronously if it can do so without blocking.
 *               If the method will complete asynchronously, it will return
 *               PP_OK_COMPLETIONPENDING. Otherwise, it will complete
 *               synchronously and return an appropriate code (see below for
 *               more information on the return code). Optional callbacks are
 *               generally more difficult to use correctly than Required
 *               callbacks, but can provide better performance for some APIs
 *               (especially APIs with buffered reads, such as PPB_URLLoader or
 *               PPB_FileIO).
 *               <br /><br />
 *               NOTE: If you use an optional callback on a background thread,
 *               and you have not created and attached a PPB_MessageLoop, then
 *               the method you invoke will fail without running and return
 *               PP_ERROR_NO_MESSAGE_LOOP.
 *
 *   - Blocking: In this case, the callback's function pointer is NULL, and the
 *               invoked method must complete synchronously. The method will
 *               run to completion and return an appropriate code when finished
 *               (see below for more information). Blocking completion
 *               callbacks are only supported on background threads.
 *               <br /><br />
 *               <code>PP_BlockUntilComplete()</code> provides a convenient way
 *               to specify blocking behavior. Refer to
 *               <code>PP_BlockUntilComplete</code> for more information.
 *
 * When the callback is run asynchronously, the result parameter passed to
 * <code>func</code> is an int32_t that, if negative indicates an error code
 * whose meaning is specific to the calling method (refer to
 * <code>pp_error.h</code> for further information). A positive or 0 value is a
 * return result indicating success whose meaning depends on the calling method
 * (e.g. number of bytes read).
 */
struct PP_CompletionCallback {
  /**
   * This value is a callback function that will be called, or NULL if this is
   * a blocking completion callback.
   */
  PP_CompletionCallback_Func func;
  /**
   * This value is a pointer to user data passed to a callback function.
   */
  void* user_data;
  /**
   * Flags used to control how non-NULL callbacks are scheduled by
   * asynchronous methods.
   */
  int32_t flags;
};
/**
 * @}
 */

#include <stdlib.h>

/**
 * @addtogroup Functions
 * @{
 */
/**
 * PP_MakeCompletionCallback() is used to create a
 * <code>PP_CompletionCallback</code>.
 *
 * <strong>Example, creating a Required callback:</strong>
 *
 * @code
 * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
 * @endcode
 *
 * <strong>Example, creating an Optional callback:</strong>
 *
 * @code
 * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
 * cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
 * @endcode
 *
 * @param[in] func A <code>PP_CompletionCallback_Func</code> that will be
 * called.
 * @param[in] user_data A pointer to user data passed to your callback
 * function. This is optional and is typically used to help track state
 * when you may have multiple callbacks pending.
 *
 * @return A <code>PP_CompletionCallback</code> structure.
 */
PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback(
    PP_CompletionCallback_Func func,
    void* user_data) {
  struct PP_CompletionCallback cc;
  cc.func = func;
  cc.user_data = user_data;
  cc.flags = PP_COMPLETIONCALLBACK_FLAG_NONE;
  return cc;
}

/**
 * PP_MakeOptionalCompletionCallback() is used to create a PP_CompletionCallback
 * with PP_COMPLETIONCALLBACK_FLAG_OPTIONAL set.
 *
 * @param[in] func A PP_CompletionCallback_Func to be called on completion.
 * @param[in] user_data A pointer to user data passed to be passed to the
 * callback function. This is optional and is typically used to help track state
 * in case of multiple pending callbacks.
 *
 * @return A PP_CompletionCallback structure.
 */
PP_INLINE struct PP_CompletionCallback PP_MakeOptionalCompletionCallback(
    PP_CompletionCallback_Func func,
    void* user_data) {
  struct PP_CompletionCallback cc = PP_MakeCompletionCallback(func, user_data);
  cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
  return cc;
}
/**
 * @}
 */

/**
 * @addtogroup Functions
 * @{
 */

/**
 * PP_RunCompletionCallback() is used to run a callback. It invokes
 * the callback function passing it user data specified on creation and
 * completion |result|.
 *
 * @param[in] cc A pointer to a <code>PP_CompletionCallback</code> that will be
 * run.
 * @param[in] result The result of the operation. Non-positive values correspond
 * to the error codes from pp_errors.h (excluding PP_OK_COMPLETIONPENDING).
 * Positive values indicate additional information such as bytes read.
 */
PP_INLINE void PP_RunCompletionCallback(struct PP_CompletionCallback* cc,
                                        int32_t result) {
  cc->func(cc->user_data, result);
}

/**
 * @}
 */

/**
 * @addtogroup Functions
 * @{
 */

 /**
 * PP_BlockUntilComplete() is used in place of an actual completion callback
 * to request blocking behavior. If specified, the calling thread will block
 * until the function completes. Blocking completion callbacks are only allowed
 * from background threads.
 *
 * @return A <code>PP_CompletionCallback</code> structure.
 */
PP_INLINE struct PP_CompletionCallback PP_BlockUntilComplete(void) {
  return PP_MakeCompletionCallback(NULL, NULL);
}

/**
 * PP_RunAndClearCompletionCallback() runs a callback and clears the reference
 * to that callback.
 *
 * This function is used when the null-ness of a completion callback is used as
 * a signal for whether a completion callback has been registered. In this
 * case, after the execution of the callback, it should be cleared. However,
 * this introduces a conflict if the completion callback wants to schedule more
 * work that involves the same completion callback again (for example, when
 * reading data from an URLLoader, one would typically queue up another read
 * callback). As a result, this function clears the pointer
 * before the provided callback is executed.
 */
PP_INLINE void PP_RunAndClearCompletionCallback(
    struct PP_CompletionCallback* cc,
    int32_t res) {
  struct PP_CompletionCallback temp = *cc;
  *cc = PP_BlockUntilComplete();
  PP_RunCompletionCallback(&temp, res);
}
/**
 * @}
 */

#endif  /* PPAPI_C_PP_COMPLETION_CALLBACK_H_ */