15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles)/* From ppb_message_loop.idl modified Thu May 9 14:59:57 2013. */ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 82a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)#ifndef PPAPI_C_PPB_MESSAGE_LOOP_H_ 92a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)#define PPAPI_C_PPB_MESSAGE_LOOP_H_ 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_bool.h" 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_completion_callback.h" 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_instance.h" 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_macros.h" 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_resource.h" 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_stdint.h" 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)#define PPB_MESSAGELOOP_INTERFACE_1_0 "PPB_MessageLoop;1.0" 192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)#define PPB_MESSAGELOOP_INTERFACE PPB_MESSAGELOOP_INTERFACE_1_0 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @file 232a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Defines the PPB_MessageLoop interface. 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @addtogroup Interfaces 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @{ 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * A message loop allows PPAPI calls to be issued on a thread. You may not 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * issue any API calls on a thread without creating a message loop. It also 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * allows you to post work to the message loop for a thread. 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * To process work posted to the message loop, as well as completion callbacks 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * for asynchronous operations, you must run the message loop via Run(). 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Note the system manages the lifetime of the instance (and all associated 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * resources). If the instance is deleted from the page, background threads may 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * suddenly see their PP_Resource handles become invalid. In this case, calls 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * will fail with PP_ERROR_BADRESOURCE. If you need to access data associated 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * with your instance, you will probably want to create some kind of threadsafe 44c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * proxy object that can handle asynchronous destruction of the instance object. 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Typical usage: 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * On the main thread: 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - Create the thread yourself (using pthreads). 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - Create the message loop resource. 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - Pass the message loop resource to your thread's main function. 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - Call PostWork() on the message loop to run functions on the thread. 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * From the background thread's main function: 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - Call AttachToCurrentThread() with the message loop resource. 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - Call Run() with the message loop resource. 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 57c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * Your callbacks should look like this: 58868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * @code 59868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * void DoMyWork(void* user_data, int32_t status) { 60868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * if (status != PP_OK) { 61868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * Cleanup(); // e.g. free user_data. 62868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * return; 63868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * } 64868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * ... do your work... 65868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * } 66868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * @endcode 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * For a C++ example, see ppapi/utility/threading/simple_thread.h 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * (You can also create the message loop resource on the background thread, 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * but then the main thread will have no reference to it should you want to 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * call PostWork()). 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * THREAD HANDLING 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The main thread has an implicitly created message loop. The main thread is 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the thread where PPP_InitializeModule and PPP_Instance functions are called. 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * You can retrieve a reference to this message loop by calling 795d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) * GetForMainThread() or, if your code is on the main thread, GetCurrent() will 805d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) * also work. 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Some special threads created by the system can not have message loops. In 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * particular, the background thread created for audio processing has this 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * requirement because it's intended to be highly responsive to keep up with 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the realtime requirements of audio processing. You can not make PPAPI calls 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * from these threads. 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Once you associate a message loop with a thread, you don't have to keep a 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * reference to it. The system will hold a reference to the message loop for as 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * long as the thread is running. The current message loop can be retrieved 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * using the GetCurrent() function. 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * It is legal to create threads in your plugin without message loops, but 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * PPAPI calls will fail unless explicitly noted in the documentation. 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * You can create a message loop object on a thread and never actually run the 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * message loop. This will allow you to call blocking PPAPI calls (via 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * PP_BlockUntilComplete()). If you make any asynchronous calls, the callbacks 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * from those calls will be queued in the message loop and never run. The same 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * thing will happen if work is scheduled after the message loop exits and 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the message loop is not run again. 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * DESTRUCTION AND ERROR HANDLING 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Often, your application will associate memory with completion callbacks. For 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * example, the C++ CompletionCallbackFactory has a small amount of 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * heap-allocated memory for each callback. This memory will be leaked if the 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * callback is never run. To avoid this memory leak, you need to be careful 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * about error handling and shutdown. 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * There are a number of cases where posted callbacks will never be run: 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - You tear down the thread (via pthreads) without "destroying" the message 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * loop (via PostQuit with should_destroy = PP_TRUE). In this case, any 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * tasks in the message queue will be lost. 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - You create a message loop, post callbacks to it, and never run it. 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - You quit the message loop via PostQuit with should_destroy set to 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * PP_FALSE. In this case, the system will assume the message loop will be 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * run again later and keep your tasks. 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * To do proper shutdown, call PostQuit with should_destroy = PP_TRUE. This 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * will prohibit future work from being posted, and will allow the message loop 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * to run until all pending tasks are run. 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * If you post a callback to a message loop that's been destroyed, or to an 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * invalid message loop, PostWork will return an error and will not run the 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * callback. This is true even for callbacks with the "required" flag set, 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * since the system may not even know what thread to issue the error callback 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * on. 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Therefore, you should check for errors from PostWork and destroy any 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * associated memory to avoid leaks. If you're using the C++ 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * CompletionCallbackFactory, use the following pattern: 137868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * @code 138868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * pp::CompletionCallback callback = factory_.NewOptionalCallback(...); 139868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * int32_t result = message_loop.PostWork(callback); 140868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * if (result != PP_OK) 141868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * callback.Run(result); 142868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) * @endcode 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This will run the callback with an error value, and assumes that the 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * implementation of your callback checks the "result" argument and returns 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * immediately on error. 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1472a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)struct PPB_MessageLoop_1_0 { 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Creates a message loop resource. 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This may be called from any thread. After your thread starts but before 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * issuing any other PPAPI calls on it, you must associate it with a message 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * loop by calling AttachToCurrentThread. 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Resource (*Create)(PP_Instance instance); 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Returns a resource identifying the message loop for the main thread. The 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * main thread always has a message loop created by the system. 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1602a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) PP_Resource (*GetForMainThread)(void); 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Returns a reference to the PPB_MessageLoop object attached to the current 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * thread. If there is no attached message loop, the return value will be 0. 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1652a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) PP_Resource (*GetCurrent)(void); 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Sets the given message loop resource as being the associated message loop 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * for the currently running thread. 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * You must call this function exactly once on a thread before making any 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * PPAPI calls. A message loop can only be attached to one thread, and the 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * message loop can not be changed later. The message loop will be attached 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * as long as the thread is running or until you quit with should_destroy 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * set to PP_TRUE. 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * If this function fails, attempting to run the message loop will fail. 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Note that you can still post work to the message loop: it will get queued 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * up should the message loop eventually be successfully attached and run. 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_OK: The message loop was successfully attached to the thread and is 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * ready to use. 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_BADRESOURCE: The given message loop resource is invalid. 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_INPROGRESS: The current thread already has a message loop 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * attached. This will always be the case for the main thread, which has 1865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * an implicit system-created message loop attached. 1875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_WRONG_THREAD: The current thread type can not have a message 1885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * loop attached to it. See the interface level discussion about these 1895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * special threads, which include realtime audio threads. 1905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t (*AttachToCurrentThread)(PP_Resource message_loop); 1925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 1935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Runs the thread message loop. Running the message loop is required for you 1945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * to get issued completion callbacks on the thread. 1955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The message loop identified by the argument must have been previously 1975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * successfully attached to the current thread. 1985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * You may not run nested message loops. Since the main thread has an 2005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * implicit message loop that the system runs, you may not call Run on the 2015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * main thread. 2025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return 2045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_OK: The message loop was successfully run. Note that on 2055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * success, the message loop will only exit when you call PostQuit(). 2065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_BADRESOURCE: The given message loop resource is invalid. 2075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_WRONG_THREAD: You are attempting to run a message loop that 2085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * has not been successfully attached to the current thread. Call 2095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * AttachToCurrentThread(). 2105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_INPROGRESS: You are attempting to call Run in a nested 2115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * fashion (Run is already on the stack). This will occur if you attempt 2125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * to call run on the main thread's message loop (see above). 2135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t (*Run)(PP_Resource message_loop); 2155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 2165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Schedules work to run on the given message loop. This may be called from 2175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * any thread. Posted work will be executed in the order it was posted when 2185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the message loop is Run(). 2195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param message_loop The message loop resource. 2215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param callback The completion callback to execute from the message loop. 2235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 224c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @param delay_ms The number of milliseconds to delay execution of the given 2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * completion callback. Passing 0 means it will get queued normally and 2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * executed in order. 2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The completion callback will be called with PP_OK as the "result" parameter 2305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * if it is run normally. It is good practice to check for PP_OK and return 2315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * early otherwise. 2325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The "required" flag on the completion callback is ignored. If there is an 2345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * error posting your callback, the error will be returned from PostWork and 2355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the callback will never be run (because there is no appropriate place to 2365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * run your callback with an error without causing unexpected threading 2375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * problems). If you associate memory with the completion callback (for 2385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * example, you're using the C++ CompletionCallbackFactory), you will need to 239c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * free this or manually run the callback. See "Destruction and error 2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * handling" above. 2415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * You can call this function before the message loop has started and the 2445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * work will get queued until the message loop is run. You can also post 2455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * work after the message loop has exited as long as should_destroy was 2465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * PP_FALSE. It will be queued until the next invocation of Run(). 2475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return 2492a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * - PP_OK: The work was posted to the message loop's queue. As described 2502a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * above, this does not mean that the work has been or will be executed 2512a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * (if you never run the message loop after posting). 2525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_BADRESOURCE: The given message loop resource is invalid. 2535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_BADARGUMENT: The function pointer for the completion callback 2545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * is null (this will be the case if you pass PP_BlockUntilComplete()). 2555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_FAILED: The message loop has been destroyed. 2565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t (*PostWork)(PP_Resource message_loop, 2585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) struct PP_CompletionCallback callback, 2595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int64_t delay_ms); 2605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 2615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Posts a quit message to the given message loop's work queue. Work posted 2625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * before that point will be processed before quitting. 2635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This may be called on the message loop registered for the current thread, 2652a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * or it may be called on the message loop registered for another thread. It 2662a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * is an error to attempt to PostQuit() the main thread loop. 2675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param should_destroy Marks the message loop as being in a destroyed state 2695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * and prevents further posting of messages. 2705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * If you quit a message loop without setting should_destroy, it will still 2725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * be attached to the thread and you can still run it again by calling Run() 2735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * again. If you destroy it, it will be detached from the current thread. 2745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return 2765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_OK: The request to quit was successfully posted. 2775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_BADRESOURCE: The message loop was invalid. 2785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread. 2795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The main thread's message loop is managed by the system and can't be 2805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * quit. 2815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t (*PostQuit)(PP_Resource message_loop, PP_Bool should_destroy); 2835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 2845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2852a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)typedef struct PPB_MessageLoop_1_0 PPB_MessageLoop; 2865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 2875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @} 2885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2902a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)#endif /* PPAPI_C_PPB_MESSAGE_LOOP_H_ */ 2915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 292