OLD | NEW |
1 // Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 #ifndef INCLUDE_DART_API_H_ | 5 #ifndef INCLUDE_DART_API_H_ |
6 #define INCLUDE_DART_API_H_ | 6 #define INCLUDE_DART_API_H_ |
7 | 7 |
8 /** \mainpage Dart Embedding API Reference | 8 /** \mainpage Dart Embedding API Reference |
9 * | 9 * |
10 * Dart is a class-based programming language for creating structured | 10 * Dart is a class-based programming language for creating structured |
(...skipping 208 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
219 * | 219 * |
220 * UNIMPLEMENTED. | 220 * UNIMPLEMENTED. |
221 * | 221 * |
222 * Requires there to be a current isolate. | 222 * Requires there to be a current isolate. |
223 */ | 223 */ |
224 DART_EXPORT Dart_Handle Dart_MakePersistentHandle(Dart_Handle object); | 224 DART_EXPORT Dart_Handle Dart_MakePersistentHandle(Dart_Handle object); |
225 | 225 |
226 // --- Initialization and Globals --- | 226 // --- Initialization and Globals --- |
227 | 227 |
228 /** | 228 /** |
229 * An isolate initialization callback function. | 229 * An isolate creation and initialization callback function. |
230 * | 230 * |
231 * This callback, provided by the embedder, is called during isolate | 231 * This callback, provided by the embedder, is called when an isolate needs |
232 * creation. It is called for all isolates, regardless of whether they | 232 * to be created. The callback should create an isolate and load the |
233 * are created via Dart_CreateIsolate or directly from Dart code. | 233 * required scripts for execution. |
234 * | 234 * |
235 * \param data Embedder-specific data used during isolate initialization. | 235 * \param error A structure into which the embedder can place a |
| 236 * C string containing an error message in the case of failures. |
236 * | 237 * |
237 * \return If the embedder returns NULL, then the isolate being | 238 * \return the embedder returns false if the creation and initialization was not |
238 * initialized will be shut down without executing any Dart code. | 239 * successful and true if successful. The embedder is responsible for |
239 * Otherwise, the embedder should return a pointer to | 240 * maintaining consistency in the case of errors (e.g: isolate is created, |
240 * embedder-specific data created during the initialization of this | 241 * but loading of scripts fails then the embedder should ensure that |
241 * isolate. This data will, in turn, be passed by the VM to all | 242 * Dart_ShutdownIsolate is called on the isolate). |
242 * isolates spawned from the isolate currently being initialized. | 243 * In the case of errors the caller is responsible for freeing the buffer |
| 244 * returned in error containing an error string. |
243 */ | 245 */ |
244 typedef void* (*Dart_IsolateInitCallback)(void* embedder_data); | 246 typedef bool (*Dart_IsolateCreateCallback)(void* callback_data, char** error); |
245 // TODO(iposva): Pass a specification of the app file being spawned. | |
246 // TODO(turnidge): We don't actually shut down the isolate on NULL yet. | |
247 // TODO(turnidge): Should we separate the two return values? | |
248 | 247 |
249 /** | 248 /** |
250 * Initializes the VM with the given commmand line flags. | 249 * Initializes the VM with the given commmand line flags. |
251 * | 250 * |
252 * \param argc The length of the arguments array. | 251 * \param argc The length of the arguments array. |
253 * \param argv An array of arguments. | 252 * \param argv An array of arguments. |
254 * \param callback A function to be called during isolate creation. | 253 * \param callback A function to be called during isolate creation. |
255 * See Dart_IsolateInitCallback. | 254 * See Dart_IsolateCreateCallback. |
256 * | 255 * |
257 * \return True if initialization is successful. | 256 * \return True if initialization is successful. |
258 */ | 257 */ |
259 DART_EXPORT bool Dart_Initialize(int argc, const char** argv, | 258 DART_EXPORT bool Dart_Initialize(int argc, const char** argv, |
260 Dart_IsolateInitCallback callback); | 259 Dart_IsolateCreateCallback callback); |
261 | 260 |
262 /** | 261 /** |
263 * Returns true if the named VM flag is set. | 262 * Returns true if the named VM flag is set. |
264 */ | 263 */ |
265 DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name); | 264 DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name); |
266 | 265 |
267 // --- Isolates --- | 266 // --- Isolates --- |
268 | 267 |
269 /** | 268 /** |
270 * An isolate is the unit of concurrency in Dart. Each isolate has | 269 * An isolate is the unit of concurrency in Dart. Each isolate has |
(...skipping 18 matching lines...) Expand all Loading... |
289 | 288 |
290 /** | 289 /** |
291 * Creates a new isolate. If snapshot data is provided, the isolate | 290 * Creates a new isolate. If snapshot data is provided, the isolate |
292 * will be started using that snapshot data. The new isolate becomes | 291 * will be started using that snapshot data. The new isolate becomes |
293 * the current isolate. | 292 * the current isolate. |
294 * | 293 * |
295 * Requires there to be no current isolate. | 294 * Requires there to be no current isolate. |
296 * | 295 * |
297 * \param snapshot A buffer containing a VM snapshot or NULL if no | 296 * \param snapshot A buffer containing a VM snapshot or NULL if no |
298 * snapshot is provided. | 297 * snapshot is provided. |
299 * \param data Embedder-specific data. See Dart_IsolateInitCallback. | |
300 * | 298 * |
301 * \return The new isolate is returned. May be NULL if an error | 299 * \return The new isolate is returned. May be NULL if an error |
302 * occurs duing isolate initialization. | 300 * occurs duing isolate initialization. |
303 */ | 301 */ |
304 DART_EXPORT Dart_Isolate Dart_CreateIsolate(const Dart_Snapshot* snapshot, | 302 DART_EXPORT Dart_Isolate Dart_CreateIsolate(const Dart_Snapshot* snapshot, |
305 void* data); | 303 void* callback_data, |
| 304 char** error); |
306 // TODO(turnidge): Document behavior when there is already a current | 305 // TODO(turnidge): Document behavior when there is already a current |
307 // isolate. | 306 // isolate. |
308 | 307 |
309 /** | 308 /** |
310 * Shuts down the current isolate. After this call, the current | 309 * Shuts down the current isolate. After this call, the current |
311 * isolate is NULL. | 310 * isolate is NULL. |
312 * | 311 * |
313 * Requires there to be a current isolate. | 312 * Requires there to be a current isolate. |
314 */ | 313 */ |
315 DART_EXPORT void Dart_ShutdownIsolate(); | 314 DART_EXPORT void Dart_ShutdownIsolate(); |
(...skipping 912 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1228 | 1227 |
1229 // --- Profiling support ---- | 1228 // --- Profiling support ---- |
1230 | 1229 |
1231 // External pprof support for gathering and dumping symbolic | 1230 // External pprof support for gathering and dumping symbolic |
1232 // information that can be used for better profile reports for | 1231 // information that can be used for better profile reports for |
1233 // dynamically generated code. | 1232 // dynamically generated code. |
1234 DART_EXPORT void Dart_InitPprofSupport(); | 1233 DART_EXPORT void Dart_InitPprofSupport(); |
1235 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); | 1234 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); |
1236 | 1235 |
1237 #endif // INCLUDE_DART_API_H_ | 1236 #endif // INCLUDE_DART_API_H_ |
OLD | NEW |