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
|
// 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.
#ifndef PPAPI_CPP_COMPLETION_CALLBACK_H_
#define PPAPI_CPP_COMPLETION_CALLBACK_H_
#include "ppapi/c/pp_completion_callback.h"
#include "ppapi/c/pp_errors.h"
#include "ppapi/cpp/logging.h"
#include "ppapi/cpp/module.h"
/// @file
/// This file defines the API to create and run a callback.
namespace pp {
/// This API enables you to implement and receive callbacks when
/// Pepper operations complete asynchronously.
class CompletionCallback {
public:
/// The default constructor will create a blocking
/// <code>CompletionCallback</code> that can be passed to a method to
/// indicate that the calling thread should be blocked until the asynchronous
/// operation corresponding to the method completes.
///
/// <strong>Note:</strong> Blocking completion callbacks are only allowed from
/// from background threads.
CompletionCallback() {
cc_ = PP_BlockUntilComplete();
}
/// A constructor for creating a <code>CompletionCallback</code>.
///
/// @param[in] func The function to be called on completion.
/// @param[in] user_data The user data to be passed to the callback function.
/// This is optional and is typically used to help track state in case of
/// multiple pending callbacks.
CompletionCallback(PP_CompletionCallback_Func func, void* user_data) {
cc_ = PP_MakeCompletionCallback(func, user_data);
}
/// A constructor for creating a <code>CompletionCallback</code> with
/// specified flags.
///
/// @param[in] func The function to be called on completion.
/// @param[in] user_data The user data to be passed to the callback function.
/// This is optional and is typically used to help track state in case of
/// multiple pending callbacks.
/// @param[in] flags Bit field combination of
/// <code>PP_CompletionCallback_Flag</code> flags used to control how
/// non-NULL callbacks are scheduled by asynchronous methods.
CompletionCallback(PP_CompletionCallback_Func func, void* user_data,
int32_t flags) {
cc_ = PP_MakeCompletionCallback(func, user_data);
cc_.flags = flags;
}
/// The set_flags() function is used to set the flags used to control
/// how non-NULL callbacks are scheduled by asynchronous methods.
///
/// @param[in] flags Bit field combination of
/// <code>PP_CompletionCallback_Flag</code> flags used to control how
/// non-NULL callbacks are scheduled by asynchronous methods.
void set_flags(int32_t flags) { cc_.flags = flags; }
/// Run() is used to run the <code>CompletionCallback</code>.
/// Normally, the system runs a <code>CompletionCallback</code> after an
/// asynchronous operation completes, but programs may wish to run the
/// <code>CompletionCallback</code> manually in order to reuse the same code
/// paths.
///
/// @param[in] result The result of the operation to be passed to the
/// callback function. Non-positive values correspond to the error codes
/// from <code>pp_errors.h</code> (excluding
/// <code>PP_OK_COMPLETIONPENDING</code>). Positive values indicate
/// additional information such as bytes read.
void Run(int32_t result) {
PP_DCHECK(cc_.func);
PP_RunCompletionCallback(&cc_, result);
}
/// IsOptional() is used to determine the setting of the
/// <code>PP_COMPLETIONCALLBACK_FLAG_OPTIONAL</code> flag. 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 Pepper execution.
///
/// @return true if this callback is optional, otherwise false.
bool IsOptional() const {
return (cc_.func == NULL ||
(cc_.flags & PP_COMPLETIONCALLBACK_FLAG_OPTIONAL) != 0);
}
/// The pp_completion_callback() function returns the underlying
/// <code>PP_CompletionCallback</code>
///
/// @return A <code>PP_CompletionCallback</code>.
const PP_CompletionCallback& pp_completion_callback() const { return cc_; }
/// The flags() function returns flags used to control how non-NULL callbacks
/// are scheduled by asynchronous methods.
///
/// @return An int32_t containing a bit field combination of
/// <code>PP_CompletionCallback_Flag</code> flags.
int32_t flags() const { return cc_.flags; }
/// MayForce() is used when implementing functions taking callbacks.
/// If the callback is required and <code>result</code> indicates that it has
/// not been scheduled, it will be forced on the main thread.
///
/// <strong>Example:</strong>
///
/// @code
///
/// int32_t OpenURL(pp::URLLoader* loader,
/// pp::URLRequestInfo* url_request_info,
/// const CompletionCallback& cc) {
/// if (loader == NULL || url_request_info == NULL)
/// return cc.MayForce(PP_ERROR_BADRESOURCE);
/// return loader->Open(*loader, *url_request_info, cc);
/// }
///
/// @endcode
///
/// @param[in] result PP_OK_COMPLETIONPENDING or the result of the completed
/// operation to be passed to the callback function. PP_OK_COMPLETIONPENDING
/// indicates that the callback has already been scheduled. Other
/// non-positive values correspond to error codes from
/// <code>pp_errors.h</code>. Positive values indicate additional information
/// such as bytes read.
///
/// @return <code>PP_OK_COMPLETIONPENDING</code> if the callback has been
/// forced, result parameter otherwise.
int32_t MayForce(int32_t result) const {
if (result == PP_OK_COMPLETIONPENDING || IsOptional())
return result;
Module::Get()->core()->CallOnMainThread(0, *this, result);
return PP_OK_COMPLETIONPENDING;
}
protected:
PP_CompletionCallback cc_;
};
/// 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>CompletionCallback</code> corresponding to a NULL callback.
CompletionCallback BlockUntilComplete();
} // namespace pp
#endif // PPAPI_CPP_COMPLETION_CALLBACK_H_
|
