1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
/* Copyright (c) 2011 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 Aug 11 14:45:09 2011. */
#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 main thread of PPAPI execution.
*/
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 main thread of PPAPI execution.
*/
PP_COMPLETIONCALLBACK_FLAG_OPTIONAL = 1 << 0
} PP_CompletionCallback_Flag;
PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_CompletionCallback_Flag, 4);
/**
* @}
*/
/**
* @addtogroup Structs
* @{
*/
/**
* Any method that takes a <code>PP_CompletionCallback</code> has the option of
* completing asynchronously if the operation would block. Such a method
* should return <code>PP_OK_COMPLETIONPENDING</code> to indicate that the
* method will complete asynchronously and notify the caller and will always be
* invoked from the main thread of PPAPI execution. If the completion callback
* is NULL, then the operation will block if necessary to complete its work.
* <code>PP_BlockUntilComplete()</code> provides a convenient way to specify
* blocking behavior. Refer to <code>PP_BlockUntilComplete</code> for more
* information.
*
* 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.
*/
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:</strong>
*
* <code>
* struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
* cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
* </code>
*
* @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() {
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_ */
|
