NPN_PluginThreadAsyncCall

« Gecko Plugin API Reference « Browser Side Plug-in API

Summary

Thread safe way to request that the browser calls a plug-in function on the browser or plugin thread (the thread on which the plug-in was initiated).

Syntax

#include <npapi.h>
 
void
NPN_PluginThreadAsyncCall(NPP plugin,
                          void (*func)(void *),
                          void *userData);

Parameters

The function has the following parameters:

plugin: Pointer to the current plug-in instance.

func: Pointer to the function to call on the correct thread.

userData: Pointer to the data to pass to the function func once called.

Returns

Nothing.

Description

Causes asynchronous execution of the specified function pointer on the "plug-in thread", passing in the specified user data pointer when it is called. The "plug-in thread" is the thread hosting the plug-in, which may be either the browser's main thread or the plug-in process if the plug-in is being executed out-of-process.

It is the application's responsibility to perform any synchronization between the thread calling NPN_PluginThreadAsyncCall() and the thread on which the call is eventually executed. In particular, the user must ensure that the function pointer remains callable and the user data is not deallocated until the browser executes the call.

There are inherent race conditions between calling this function and termination of the plug-in instance. The browser might not execute calls successfully registered with this API call during plug-in termination. Plug-ins should perform appropriate synchronization with the code in their NPP_Destroy() routine to ensure correct execution and avoid memory leaks.

Calling NPN_PluginThreadAsyncCall() on the "browser main thread" or the "plug-in thread" is legal; the call to NPN_PluginThreadAsyncCall() returns immediately. After control returns to the browser, it is free to call the function with its argument from this thread.