ppapi/cpp/core.h

   1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef PPAPI_CPP_CORE_H_
   6 #define PPAPI_CPP_CORE_H_
   7
   8 #include "ppapi/c/ppb_core.h"
   9
  10 /// @file
  11 /// This file defines APIs related to memory management, time, and threads.
  12
  13 namespace pp {
  14
  15 class CompletionCallback;
  16 class Module;
  17
  18 /// APIs related to memory management, time, and threads.
  19 class Core {
  20  public:
  21   // Note that we explicitly don't expose Resource& versions of this function
  22   // since Resource will normally manage the refcount properly. These should
  23   // be called only when doing manual management on raw PP_Resource handles,
  24   // which should be fairly rare.
  25
  26   /// AddRefResource() increments the reference count for the provided
  27   /// <code>resource</code>.
  28   ///
  29   /// @param[in] resource A <code>PP_Resource</code> corresponding to a
  30   /// resource.
  31   void AddRefResource(PP_Resource resource) {
  32     interface_->AddRefResource(resource);
  33   }
  34
  35   /// ReleaseResource() decrements the reference count for the provided
  36   /// <code>resource</code>. The resource will be deallocated if the
  37   /// reference count reaches zero.
  38   ///
  39   /// @param[in] resource A <code>PP_Resource</code> corresponding to a
  40   /// resource.
  41   void ReleaseResource(PP_Resource resource) {
  42     interface_->ReleaseResource(resource);
  43   }
  44
  45   /// GetTime() returns the "wall clock time" according to the
  46   /// browser.
  47   ///
  48   /// @return A <code>PP_Time</code> containing the "wall clock time" according
  49   /// to the browser.
  50   PP_Time GetTime() {
  51     return interface_->GetTime();
  52   }
  53
  54   /// GetTimeTicks() returns the "tick time" according to the browser.
  55   /// This clock is used by the browser when passing some event times to the
  56   /// module (for example, using the
  57   /// <code>PP_InputEvent::time_stamp_seconds</code> field). It is not
  58   /// correlated to any actual wall clock time (like GetTime()). Because
  59   /// of this, it will not change if the user changes their computer clock.
  60   ///
  61   /// @return A <code>PP_TimeTicks</code> containing the "tick time" according
  62   /// to the browser.
  63   PP_TimeTicks GetTimeTicks() {
  64     return interface_->GetTimeTicks();
  65   }
  66
  67   /// CallOnMainThread() schedules work to be executed on the main pepper
  68   /// thread after the specified delay. The delay may be 0 to specify a call
  69   /// back as soon as possible.
  70   ///
  71   /// The |result| parameter will just be passed as the second argument to the
  72   /// callback. Many applications won't need this, but it allows a module to
  73   /// emulate calls of some callbacks which do use this value.
  74   ///
  75   /// <strong>Note:</strong> CallOnMainThread(), even when used from the main
  76   /// thread with a delay of 0 milliseconds, will never directly invoke the
  77   /// callback.  Even in this case, the callback will be scheduled
  78   /// asynchronously.
  79   ///
  80   /// <strong>Note:</strong> If the browser is shutting down or if the module
  81   /// has no instances, then the callback function may not be called.
  82   ///
  83   /// @param[in] delay_in_milliseconds An int32_t delay in milliseconds.
  84   /// @param[in] callback A <code>CompletionCallback</code> callback function
  85   /// that the browser will call after the specified delay.
  86   /// @param[in] result An int32_t that the browser will pass to the given
  87   /// <code>CompletionCallback</code>.
  88   void CallOnMainThread(int32_t delay_in_milliseconds,
  89                         const CompletionCallback& callback,
  90                         int32_t result = 0);
  91
  92
  93   /// IsMainThread() returns true if the current thread is the main pepper
  94   /// thread.
  95   ///
  96   /// This function is useful for implementing sanity checks, and deciding if
  97   /// dispatching using CallOnMainThread() is required.
  98   ///
  99   /// @return true if the current thread is the main pepper thread, otherwise
 100   /// false.
 101   bool IsMainThread();
 102
 103  private:
 104   // Allow Module to construct.
 105   friend class Module;
 106
 107   // Only module should make this class so this constructor is private.
 108   Core(const PPB_Core* inter) : interface_(inter) {}
 109
 110   // Copy and assignment are disallowed.
 111   Core(const Core& other);
 112   Core& operator=(const Core& other);
 113
 114   const PPB_Core* interface_;
 115 };
 116
 117 }  // namespace pp
 118
 119 #endif  // PPAPI_CPP_CORE_H_