Index: ppapi/cpp/dev/message_loop_dev.h |
diff --git a/ppapi/cpp/dev/message_loop_dev.h b/ppapi/cpp/dev/message_loop_dev.h |
deleted file mode 100644 |
index b3aebab3cacecf8206d862a927a5b9e7de146f40..0000000000000000000000000000000000000000 |
--- a/ppapi/cpp/dev/message_loop_dev.h |
+++ /dev/null |
@@ -1,261 +0,0 @@ |
-// 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. |
- |
-#ifndef PPAPI_CPP_DEV_MESSAGE_LOOP_DEV_H_ |
-#define PPAPI_CPP_DEV_MESSAGE_LOOP_DEV_H_ |
- |
-#include "ppapi/cpp/resource.h" |
- |
-namespace pp { |
- |
-class CompletionCallback; |
-class InstanceHandle; |
- |
-/// A message loop allows PPAPI calls to be issued on a thread. You may not |
-/// issue any API calls on a thread without creating a message loop. It also |
-/// allows you to post work to the message loop for a thread. |
-/// |
-/// To process work posted to the message loop, as well as completion callbacks |
-/// for asynchronous operations, you must run the message loop via Run(). |
-/// |
-/// Note the system manages the lifetime of the instance (and all associated |
-/// resources). If the instance is deleted from the page, background threads may |
-/// suddenly see their PP_Resource handles become invalid. In this case, calls |
-/// will fail with PP_ERROR_BADRESOURCE. If you need to access data associated |
-/// with your instance, you will probably want to create some kind of threadsafe |
-/// proxy object that can handle asynchonous destruction of the instance object. |
-/// |
-/// Typical usage: |
-/// On the main thread: |
-/// - Create the thread yourself (using pthreads). |
-/// - Create the message loop resource. |
-/// - Pass the message loop resource to your thread's main function. |
-/// - Call PostWork() on the message loop to run functions on the thread. |
-/// |
-/// From the background thread's main function: |
-/// - Call AttachToCurrentThread() with the message loop resource. |
-/// - Call Run() with the message loop resource. |
-/// |
-/// Your callacks should look like this: |
-/// void DoMyWork(void* user_data, int32_t status) { |
-/// if (status != PP_OK) { |
-/// Cleanup(); // e.g. free user_data. |
-/// return; |
-/// } |
-/// ... do your work... |
-/// } |
-/// For a C++ example, see ppapi/utility/threading/simple_thread.h |
-/// |
-/// (You can also create the message loop resource on the background thread, |
-/// but then the main thread will have no reference to it should you want to |
-/// call PostWork()). |
-/// |
-/// |
-/// THREAD HANDLING |
-/// |
-/// The main thread has an implicitly created message loop. The main thread is |
-/// the thread where PPP_InitializeModule and PPP_Instance functions are called. |
-/// You can retrieve a reference to this message loop by calling |
-/// GetForMainThread() or, if your code is on the main thread, |
-/// GetForCurrentThread() will also work. |
-/// |
-/// Some special threads created by the system can not have message loops. In |
-/// particular, the background thread created for audio processing has this |
-/// requirement because it's intended to be highly responsive to keep up with |
-/// the realtime requirements of audio processing. You can not make PPAPI calls |
-/// from these threads. |
-/// |
-/// Once you associate a message loop with a thread, you don't have to keep a |
-/// reference to it. The system will hold a reference to the message loop for as |
-/// long as the thread is running. The current message loop can be retrieved |
-/// using the GetCurrent() function. |
-/// |
-/// It is legal to create threads in your plugin without message loops, but |
-/// PPAPI calls will fail unless explicitly noted in the documentation. |
-/// |
-/// You can create a message loop object on a thread and never actually run the |
-/// message loop. This will allow you to call blocking PPAPI calls (via |
-/// PP_BlockUntilComplete()). If you make any asynchronous calls, the callbacks |
-/// from those calls will be queued in the message loop and never run. The same |
-/// thing will happen if work is scheduled after the message loop exits and |
-/// the message loop is not run again. |
-/// |
-/// |
-/// DESTRUCTION AND ERROR HANDLING |
-/// |
-/// Often, your application will associate memory with completion callbacks. For |
-/// example, the C++ CompletionCallbackFactory has a small amount of |
-/// heap-allocated memory for each callback. This memory will be leaked if the |
-/// callback is never run. To avoid this memory leak, you need to be careful |
-/// about error handling and shutdown. |
-/// |
-/// There are a number of cases where posted callbacks will never be run: |
-/// |
-/// - You tear down the thread (via pthreads) without "destroying" the message |
-/// loop (via PostQuit with should_destroy = PP_TRUE). In this case, any |
-/// tasks in the message queue will be lost. |
-/// |
-/// - You create a message loop, post callbacks to it, and never run it. |
-/// |
-/// - You quit the message loop via PostQuit with should_destroy set to |
-/// PP_FALSE. In this case, the system will assume the message loop will be |
-/// run again later and keep your tasks. |
-/// |
-/// To do proper shutdown, call PostQuit with should_destroy = PP_TRUE. This |
-/// will prohibit future work from being posted, and will allow the message loop |
-/// to run until all pending tasks are run. |
-/// |
-/// If you post a callback to a message loop that's been destroyed, or to an |
-/// invalid message loop, PostWork will return an error and will not run the |
-/// callback. This is true even for callbacks with the "required" flag set, |
-/// since the system may not even know what thread to issue the error callback |
-/// on. |
-/// |
-/// Therefore, you should check for errors from PostWork and destroy any |
-/// associated memory to avoid leaks. If you're using the C++ |
-/// CompletionCallbackFactory, use the following pattern: |
-/// |
-/// pp::CompletionCallback callback = factory_.NewOptionalCallback(...); |
-/// int32_t result = message_loop.PostWork(callback); |
-/// if (result != PP_OK_COMPLETIONPENDING) |
-/// callback.Run(result); |
-/// |
-/// This will run the callback with an error value, and assumes that the |
-/// implementation of your callback checks the "result" argument and returns |
-/// immediately on error. |
-class MessageLoop_Dev : public Resource { |
- public: |
- /// Creates an is_null() MessageLoop resource. |
- MessageLoop_Dev(); |
- |
- /// Creates a message loop associated with the given instance. The resource |
- /// will be is_null() on failure. |
- /// |
- /// This may be called from any thread. After your thread starts but before |
- /// issuing any other PPAPI calls on it, you must associate it with a message |
- /// loop by calling AttachToCurrentThread. |
- explicit MessageLoop_Dev(const InstanceHandle& instance); |
- |
- MessageLoop_Dev(const MessageLoop_Dev& other); |
- |
- /// Takes an additional ref to the resource. |
- explicit MessageLoop_Dev(PP_Resource pp_message_loop); |
- |
- static MessageLoop_Dev GetForMainThread(); |
- static MessageLoop_Dev GetCurrent(); |
- |
- /// Sets the given message loop resource as being the associated message loop |
- /// for the currently running thread. |
- /// |
- /// You must call this function exactly once on a thread before making any |
- /// PPAPI calls. A message loop can only be attached to one thread, and the |
- /// message loop can not be changed later. The message loop will be attached |
- /// as long as the thread is running or until you quit with should_destroy |
- /// set to PP_TRUE. |
- /// |
- /// If this function fails, attempting to run the message loop will fail. |
- /// Note that you can still post work to the message loop: it will get queued |
- /// up should the message loop eventually be successfully attached and run. |
- /// |
- /// @return |
- /// - PP_OK: The message loop was successfully attached to the thread and is |
- /// ready to use. |
- /// - PP_ERROR_BADRESOURCE: The given message loop resource is invalid. |
- /// - PP_ERROR_INPROGRESS: The current thread already has a message loop |
- /// attached. This will always be the case for the main thread, which has |
- /// an implicit system-created message loop attached. |
- /// - PP_ERROR_WRONG_THREAD: The current thread type can not have a message |
- /// loop attached to it. See the interface level discussion about these |
- /// special threads, which include realtime audio threads. |
- int32_t AttachToCurrentThread(); |
- |
- /// Runs the thread message loop. Running the message loop is required for |
- /// you to get issued completion callbacks on the thread. |
- /// |
- /// The message loop identified by the argument must have been previously |
- /// successfully attached to the current thread. |
- /// |
- /// You may not run nested message loops. Since the main thread has an |
- /// implicit message loop that the system runs, you may not call Run on the |
- /// main thread. |
- /// |
- /// @return |
- /// - PP_OK: The message loop was successfully run. Note that on |
- /// success, the message loop will only exit when you call PostQuit(). |
- /// - PP_ERROR_BADRESOURCE: The given message loop resource is invalid. |
- /// - PP_ERROR_WRONG_THREAD: You are attempting to run a message loop that |
- /// has not been successfully attached to the current thread. Call |
- /// AttachToCurrentThread(). |
- /// - PP_ERROR_INPROGRESS: You are attempting to call Run in a nested |
- /// fashion (Run is already on the stack). This will occur if you attempt |
- /// to call run on the main thread's message loop (see above). |
- int32_t Run(); |
- |
- /// Schedules work to run on the given message loop. This may be called from |
- /// any thread. Posted work will be executed in the order it was posted when |
- /// the message loop is Run(). |
- /// |
- /// @param callback A pointer to the completion callback to execute from the |
- /// message loop. |
- /// |
- /// @param delay_ms The number of millseconds to delay execution of the given |
- /// completion callback. Passing 0 means it will get queued normally and |
- /// executed in order. |
- /// |
- /// |
- /// The completion callback will be called with PP_OK as the "result" |
- /// parameter if it is run normally. It is good practice to check for PP_OK |
- /// and return early otherwise. |
- /// |
- /// The "required" flag on the completion callback is ignored. If there is an |
- /// error posting your callback, the error will be returned from PostWork and |
- /// the callback will never be run (because there is no appropriate place to |
- /// run your callback with an error without causing unexpected threading |
- /// problems). If you associate memory with the completion callback (for |
- /// example, you're using the C++ CompletionCallbackFactory), you will need to |
- /// free this or manually run the callback. See "Desctruction and error |
- /// handling" above. |
- /// |
- /// |
- /// You can call this function before the message loop has started and the |
- /// work will get queued until the message loop is run. You can also post |
- /// work after the message loop has exited as long as should_destroy was |
- /// PP_FALSE. It will be queued until the next invocation of Run(). |
- /// |
- /// @return |
- /// - PP_OK_COMPLETIONPENDING: The work was posted to the message loop's |
- /// queue. As described above, this does not mean that the work has been |
- /// or will be executed (if you never run the message loop after posting). |
- /// - PP_ERROR_BADRESOURCE: The given message loop resource is invalid. |
- /// - PP_ERROR_BADARGUMENT: The function pointer for the completion callback |
- /// is null (this will be the case if you pass PP_BlockUntilComplete()). |
- /// - PP_ERROR_FAILED: The message loop has been destroyed. |
- int32_t PostWork(const CompletionCallback& callback, |
- int64_t delay_ms = 0); |
- |
- /// Posts a quit message to the given message loop's work queue. Work posted |
- /// before that point will be processed before quitting. |
- /// |
- /// This may be called on the message loop registered for the current thread, |
- /// or it may be called on the message loop registered for another thread. |
- /// |
- /// @param should_destroy Marks the message loop as being in a destroyed |
- /// state and prevents further posting of messages. |
- /// |
- /// If you quit a message loop without setting should_destroy, it will still |
- /// be attached to the thread and you can still run it again by calling Run() |
- /// again. If you destroy it, it will be detached from the current thread. |
- /// |
- /// @return |
- /// - PP_OK: The request to quit was successfully posted. |
- /// - PP_ERROR_BADRESOURCE: The message loop was invalid. |
- /// - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread. |
- /// The main thread's message loop is managed by the system and can't be |
- /// quit. |
- int32_t PostQuit(bool should_destroy); |
-}; |
- |
-} // namespace pp |
- |
-#endif // PPAPI_CPP_DEV_MESSAGE_LOOP_DEV_H_ |