| 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 75 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 86 * Local handles are allocated within the current scope (see | 86 * Local handles are allocated within the current scope (see |
| 87 * Dart_EnterScope) and go away when the current scope exits. Unless | 87 * Dart_EnterScope) and go away when the current scope exits. Unless |
| 88 * otherwise indicated, callers should assume that all functions in | 88 * otherwise indicated, callers should assume that all functions in |
| 89 * the Dart embedding api return local handles. | 89 * the Dart embedding api return local handles. |
| 90 * | 90 * |
| 91 * Persistent handles are allocated within the current isolate. They | 91 * Persistent handles are allocated within the current isolate. They |
| 92 * can be used to store objects across scopes. Persistent handles have | 92 * can be used to store objects across scopes. Persistent handles have |
| 93 * the lifetime of the current isolate unless they are explicitly | 93 * the lifetime of the current isolate unless they are explicitly |
| 94 * deallocated (see Dart_DeletePersistentHandle). | 94 * deallocated (see Dart_DeletePersistentHandle). |
| 95 */ | 95 */ |
| 96 typedef void* Dart_Handle; | 96 typedef struct _Dart_Handle* Dart_Handle; |
| 97 | 97 |
| 98 /** | 98 /** |
| 99 * Is this an error handle? | 99 * Is this an error handle? |
| 100 * | 100 * |
| 101 * Requires there to be a current isolate. | 101 * Requires there to be a current isolate. |
| 102 */ | 102 */ |
| 103 DART_EXPORT bool Dart_IsError(const Dart_Handle& handle); | 103 DART_EXPORT bool Dart_IsError(const Dart_Handle& handle); |
| 104 | 104 |
| 105 /** | 105 /** |
| 106 * Gets the error message from an error handle. | 106 * Gets the error message from an error handle. |
| (...skipping 170 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 277 * its own memory and thread of control. No state is shared between | 277 * its own memory and thread of control. No state is shared between |
| 278 * isolates. Instead, isolates communicate by message passing. | 278 * isolates. Instead, isolates communicate by message passing. |
| 279 * | 279 * |
| 280 * Each thread keeps track of its current isolate, which is the | 280 * Each thread keeps track of its current isolate, which is the |
| 281 * isolate which is ready to execute on the current thread. The | 281 * isolate which is ready to execute on the current thread. The |
| 282 * current isolate may be NULL, in which case no isolate is ready to | 282 * current isolate may be NULL, in which case no isolate is ready to |
| 283 * execute. Most of the Dart apis require there to be a current | 283 * execute. Most of the Dart apis require there to be a current |
| 284 * isolate in order to function without error. The current isolate is | 284 * isolate in order to function without error. The current isolate is |
| 285 * set by any call to Dart_CreateIsolate or Dart_EnterIsolate. | 285 * set by any call to Dart_CreateIsolate or Dart_EnterIsolate. |
| 286 */ | 286 */ |
| 287 typedef void* Dart_Isolate; | 287 typedef struct _Dart_Isolate* Dart_Isolate; |
| 288 | 288 |
| 289 /** | 289 /** |
| 290 * A buffer containing a snapshot of the Dart VM. A snapshot can be | 290 * Creates a new isolate. The new isolate becomes the current isolate. |
| 291 * used to restore the VM quickly to a saved state and is useful for | 291 * |
| 292 * fast startup. | 292 * A snapshot can be used to restore the VM quickly to a saved state |
| 293 */ | 293 * and is useful for fast startup. If snapshot data is provided, the |
| 294 typedef void Dart_Snapshot; | 294 * isolate will be started using that snapshot data. |
| 295 | |
| 296 /** | |
| 297 * Creates a new isolate. If snapshot data is provided, the isolate | |
| 298 * will be started using that snapshot data. The new isolate becomes | |
| 299 * the current isolate. | |
| 300 * | 295 * |
| 301 * Requires there to be no current isolate. | 296 * Requires there to be no current isolate. |
| 302 * | 297 * |
| 303 * \param snapshot A buffer containing a VM snapshot or NULL if no | 298 * \param snapshot A buffer containing a VM snapshot or NULL if no |
| 304 * snapshot is provided. | 299 * snapshot is provided. |
| 305 * | 300 * |
| 306 * \return The new isolate is returned. May be NULL if an error | 301 * \return The new isolate is returned. May be NULL if an error |
| 307 * occurs duing isolate initialization. | 302 * occurs duing isolate initialization. |
| 308 */ | 303 */ |
| 309 DART_EXPORT Dart_Isolate Dart_CreateIsolate(const Dart_Snapshot* snapshot, | 304 DART_EXPORT Dart_Isolate Dart_CreateIsolate(const uint8_t* snapshot, |
| 310 void* callback_data, | 305 void* callback_data, |
| 311 char** error); | 306 char** error); |
| 312 // TODO(turnidge): Document behavior when there is already a current | 307 // TODO(turnidge): Document behavior when there is already a current |
| 313 // isolate. | 308 // isolate. |
| 314 | 309 |
| 315 /** | 310 /** |
| 316 * Shuts down the current isolate. After this call, the current | 311 * Shuts down the current isolate. After this call, the current |
| 317 * isolate is NULL. | 312 * isolate is NULL. |
| 318 * | 313 * |
| 319 * Requires there to be a current isolate. | 314 * Requires there to be a current isolate. |
| (...skipping 26 matching lines...) Expand all Loading... |
| 346 */ | 341 */ |
| 347 DART_EXPORT void Dart_ExitIsolate(); | 342 DART_EXPORT void Dart_ExitIsolate(); |
| 348 // TODO(turnidge): We don't want users of the api to be able to exit a | 343 // TODO(turnidge): We don't want users of the api to be able to exit a |
| 349 // "pure" dart isolate. Implement and document. | 344 // "pure" dart isolate. Implement and document. |
| 350 | 345 |
| 351 /** | 346 /** |
| 352 * Creates a snapshot of the state of the current isolate. | 347 * Creates a snapshot of the state of the current isolate. |
| 353 */ | 348 */ |
| 354 DART_EXPORT Dart_Handle Dart_CreateSnapshot(uint8_t** snaphot_buffer, | 349 DART_EXPORT Dart_Handle Dart_CreateSnapshot(uint8_t** snaphot_buffer, |
| 355 intptr_t* snapshot_size); | 350 intptr_t* snapshot_size); |
| 356 // TODO(turnidge): Does this include the current script or only libs? | |
| 357 // is it possible to take a snapshot and load more scripts into it? | |
| 358 | 351 |
| 359 // --- Messages and Ports --- | 352 // --- Messages and Ports --- |
| 360 | 353 |
| 361 /** | 354 /** |
| 362 * Messages are used to communicate between isolates. | 355 * Messages are used to communicate between isolates. |
| 363 */ | 356 */ |
| 364 typedef void* Dart_Message; | 357 typedef struct _Dart_Message* Dart_Message; |
| 365 | 358 |
| 366 /** | 359 /** |
| 367 * A port is used to send or receive inter-isolate messages | 360 * A port is used to send or receive inter-isolate messages |
| 368 */ | 361 */ |
| 369 typedef int64_t Dart_Port; | 362 typedef int64_t Dart_Port; |
| 370 | 363 |
| 371 const Dart_Port kNoReplyPort = 0; | 364 const Dart_Port kNoReplyPort = 0; |
| 372 | 365 |
| 373 /** | 366 /** |
| 374 * A message posting callback. | 367 * A message posting callback. |
| (...skipping 736 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1111 // --- Native functions --- | 1104 // --- Native functions --- |
| 1112 | 1105 |
| 1113 /** | 1106 /** |
| 1114 * The arguments to a native function. | 1107 * The arguments to a native function. |
| 1115 * | 1108 * |
| 1116 * This object is passed to a native function to represent its | 1109 * This object is passed to a native function to represent its |
| 1117 * arguments and return value. It allows access to the arguments to a | 1110 * arguments and return value. It allows access to the arguments to a |
| 1118 * native function by index. It also allows the return value of a | 1111 * native function by index. It also allows the return value of a |
| 1119 * native function to be set. | 1112 * native function to be set. |
| 1120 */ | 1113 */ |
| 1121 typedef void* Dart_NativeArguments; | 1114 typedef struct _Dart_NativeArguments* Dart_NativeArguments; |
| 1122 | 1115 |
| 1123 /** | 1116 /** |
| 1124 * Gets the native argument at some index. | 1117 * Gets the native argument at some index. |
| 1125 */ | 1118 */ |
| 1126 DART_EXPORT Dart_Handle Dart_GetNativeArgument(Dart_NativeArguments args, | 1119 DART_EXPORT Dart_Handle Dart_GetNativeArgument(Dart_NativeArguments args, |
| 1127 int index); | 1120 int index); |
| 1128 // TODO(turnidge): Specify the behavior of an out-of-bounds access. | 1121 // TODO(turnidge): Specify the behavior of an out-of-bounds access. |
| 1129 | 1122 |
| 1130 /** | 1123 /** |
| 1131 * Gets the number of native arguments. | 1124 * Gets the number of native arguments. |
| (...skipping 102 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1234 | 1227 |
| 1235 // --- Profiling support ---- | 1228 // --- Profiling support ---- |
| 1236 | 1229 |
| 1237 // External pprof support for gathering and dumping symbolic | 1230 // External pprof support for gathering and dumping symbolic |
| 1238 // information that can be used for better profile reports for | 1231 // information that can be used for better profile reports for |
| 1239 // dynamically generated code. | 1232 // dynamically generated code. |
| 1240 DART_EXPORT void Dart_InitPprofSupport(); | 1233 DART_EXPORT void Dart_InitPprofSupport(); |
| 1241 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); | 1234 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); |
| 1242 | 1235 |
| 1243 #endif // INCLUDE_DART_API_H_ | 1236 #endif // INCLUDE_DART_API_H_ |
| OLD | NEW |