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 217 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
228 /** | 228 /** |
229 * An isolate creation and initialization callback function. | 229 * An isolate creation and initialization callback function. |
230 * | 230 * |
231 * This callback, provided by the embedder, is called when an isolate needs | 231 * This callback, provided by the embedder, is called when an isolate needs |
232 * to be created. The callback should create an isolate and load the | 232 * to be created. The callback should create an isolate and load the |
233 * required scripts for execution. | 233 * required scripts for execution. |
234 * | 234 * |
235 * \param error A structure into which the embedder can place a | 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 * C string containing an error message in the case of failures. |
237 * | 237 * |
238 * \return the embedder returns false if the creation and initialization was not | 238 * \return The embedder returns false if the creation and initialization was not |
239 * successful and true if successful. The embedder is responsible for | 239 * successful and true if successful. The embedder is responsible for |
240 * maintaining consistency in the case of errors (e.g: isolate is created, | 240 * maintaining consistency in the case of errors (e.g: isolate is created, |
241 * but loading of scripts fails then the embedder should ensure that | 241 * but loading of scripts fails then the embedder should ensure that |
242 * Dart_ShutdownIsolate is called on the isolate). | 242 * Dart_ShutdownIsolate is called on the isolate). |
243 * In the case of errors the caller is responsible for freeing the buffer | 243 * In the case of errors the caller is responsible for freeing the buffer |
244 * returned in error containing an error string. | 244 * returned in error containing an error string. |
245 */ | 245 */ |
246 typedef bool (*Dart_IsolateCreateCallback)(void* callback_data, char** error); | 246 typedef bool (*Dart_IsolateCreateCallback)(void* callback_data, char** error); |
247 | 247 |
248 /** | 248 /** |
| 249 * An isolate interrupt callback function. |
| 250 * |
| 251 * This callback, provided by the embedder, is called when an isolate |
| 252 * is interrupted as a result of a call to Dart_InterruptIsolate(). |
| 253 * When the callback is called, Dart_CurrentIsolate can be used to |
| 254 * figure out which isolate is being interrupted. |
| 255 * |
| 256 * \return The embedder returns true if the isolate should continue |
| 257 * execution. If the embedder returns false, the isolate will be |
| 258 * unwound (currently unimplemented). |
| 259 */ |
| 260 typedef bool (*Dart_IsolateInterruptCallback)(); |
| 261 // TODO(turnidge): Define and implement unwinding. |
| 262 |
| 263 /** |
249 * Initializes the VM. | 264 * Initializes the VM. |
250 * | 265 * |
251 * \param callback A function to be called during isolate creation. | 266 * \param create A function to be called during isolate creation. |
252 * See Dart_IsolateCreateCallback. | 267 * See Dart_IsolateCreateCallback. |
| 268 * \param interrupt A function to be called when an isolate is interrupted. |
| 269 * See Dart_IsolateInterruptCallback. |
253 * | 270 * |
254 * \return True if initialization is successful. | 271 * \return True if initialization is successful. |
255 */ | 272 */ |
256 DART_EXPORT bool Dart_Initialize(Dart_IsolateCreateCallback callback); | 273 DART_EXPORT bool Dart_Initialize(Dart_IsolateCreateCallback create, |
| 274 Dart_IsolateInterruptCallback interrupt); |
257 | 275 |
258 /** | 276 /** |
259 * Sets command line flags. Should be called before Dart_Initialize. | 277 * Sets command line flags. Should be called before Dart_Initialize. |
260 * | 278 * |
261 * \param argc The length of the arguments array. | 279 * \param argc The length of the arguments array. |
262 * \param argv An array of arguments. | 280 * \param argv An array of arguments. |
263 * | 281 * |
264 * \return True if VM flags set successfully. | 282 * \return True if VM flags set successfully. |
265 */ | 283 */ |
266 DART_EXPORT bool Dart_SetVMFlags(int argc, const char** argv); | 284 DART_EXPORT bool Dart_SetVMFlags(int argc, const char** argv); |
(...skipping 111 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
378 * until the next call to Dart_ExitScope. | 396 * until the next call to Dart_ExitScope. |
379 * \param size Returns the size of the buffer. | 397 * \param size Returns the size of the buffer. |
380 * | 398 * |
381 * \return A valid handle if no error occurs during the operation. | 399 * \return A valid handle if no error occurs during the operation. |
382 */ | 400 */ |
383 DART_EXPORT Dart_Handle Dart_CreateScriptSnapshot(Dart_Handle library, | 401 DART_EXPORT Dart_Handle Dart_CreateScriptSnapshot(Dart_Handle library, |
384 uint8_t** buffer, | 402 uint8_t** buffer, |
385 intptr_t* size); | 403 intptr_t* size); |
386 | 404 |
387 | 405 |
| 406 /** |
| 407 * Schedules an interrupt for the specified isolate. |
| 408 * |
| 409 * Note that the interrupt does not occur immediately. In fact, if |
| 410 * 'isolate' does not execute any further Dart code, then the |
| 411 * interrupt will not occur at all. If and when the isolate is |
| 412 * interrupted, the isolate interrupt callback will be invoked with |
| 413 * 'isolate' as the current isolate (see |
| 414 * Dart_IsolateInterruptCallback). |
| 415 * |
| 416 * \param isolate The isolate to be interrupted. |
| 417 */ |
| 418 DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate); |
| 419 |
388 // --- Messages and Ports --- | 420 // --- Messages and Ports --- |
389 | 421 |
390 /** | 422 /** |
391 * Messages are used to communicate between isolates. | 423 * Messages are used to communicate between isolates. |
392 */ | 424 */ |
393 typedef struct _Dart_Message* Dart_Message; | 425 typedef struct _Dart_Message* Dart_Message; |
394 | 426 |
395 /** | 427 /** |
396 * A port is used to send or receive inter-isolate messages | 428 * A port is used to send or receive inter-isolate messages |
397 */ | 429 */ |
(...skipping 437 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
835 /** | 867 /** |
836 * Retrieves the peer pointer associated with an external String. | 868 * Retrieves the peer pointer associated with an external String. |
837 */ | 869 */ |
838 DART_EXPORT Dart_Handle Dart_ExternalStringGetPeer(Dart_Handle object, | 870 DART_EXPORT Dart_Handle Dart_ExternalStringGetPeer(Dart_Handle object, |
839 void** peer); | 871 void** peer); |
840 | 872 |
841 | 873 |
842 /** | 874 /** |
843 * Returns a String which references an external array of 8-bit codepoints. | 875 * Returns a String which references an external array of 8-bit codepoints. |
844 * | 876 * |
845 * \param value An array of 8-bit codepoints. This array must not move. | 877 * \param value An array of 8-bit codepoints. This array must not move. |
846 * \param length The length of the codepoints array. | 878 * \param length The length of the codepoints array. |
847 * \param peer An external pointer to associate with this string. | 879 * \param peer An external pointer to associate with this string. |
848 * \param callback A callback to be called when this string is finalized. | 880 * \param callback A callback to be called when this string is finalized. |
849 * | 881 * |
850 * \return The String object if no error occurs. Otherwise returns | 882 * \return The String object if no error occurs. Otherwise returns |
851 * an error handle. | 883 * an error handle. |
852 */ | 884 */ |
853 DART_EXPORT Dart_Handle Dart_NewExternalString8(const uint8_t* codepoints, | 885 DART_EXPORT Dart_Handle Dart_NewExternalString8(const uint8_t* codepoints, |
854 intptr_t length, | 886 intptr_t length, |
855 void* peer, | 887 void* peer, |
856 Dart_PeerFinalizer callback); | 888 Dart_PeerFinalizer callback); |
857 | 889 |
858 /** | 890 /** |
859 * Returns a String which references an external array of 16-bit codepoints. | 891 * Returns a String which references an external array of 16-bit codepoints. |
860 * | 892 * |
861 * \param value An array of 16-bit codepoints. This array must not move. | 893 * \param value An array of 16-bit codepoints. This array must not move. |
862 * \param length The length of the codepoints array. | 894 * \param length The length of the codepoints array. |
863 * \param peer An external pointer to associate with this string. | 895 * \param peer An external pointer to associate with this string. |
864 * \param callback A callback to be called when this string is finalized. | 896 * \param callback A callback to be called when this string is finalized. |
865 * | 897 * |
866 * \return The String object if no error occurs. Otherwise returns | 898 * \return The String object if no error occurs. Otherwise returns |
867 * an error handle. | 899 * an error handle. |
868 */ | 900 */ |
869 DART_EXPORT Dart_Handle Dart_NewExternalString16(const uint16_t* codepoints, | 901 DART_EXPORT Dart_Handle Dart_NewExternalString16(const uint16_t* codepoints, |
870 intptr_t length, | 902 intptr_t length, |
871 void* peer, | 903 void* peer, |
872 Dart_PeerFinalizer callback); | 904 Dart_PeerFinalizer callback); |
873 | 905 |
874 /** | 906 /** |
875 * Returns a String which references an external array of 32-bit codepoints. | 907 * Returns a String which references an external array of 32-bit codepoints. |
876 * | 908 * |
877 * \param value An array of 32-bit codepoints. This array must not move. | 909 * \param value An array of 32-bit codepoints. This array must not move. |
878 * \param length The length of the codepoints array. | 910 * \param length The length of the codepoints array. |
879 * \param peer An external pointer to associate with this string. | 911 * \param peer An external pointer to associate with this string. |
880 * \param callback A callback to be called when this string is finalized. | 912 * \param callback A callback to be called when this string is finalized. |
881 * | 913 * |
882 * \return The String object if no error occurs. Otherwise returns | 914 * \return The String object if no error occurs. Otherwise returns |
883 * an error handle. | 915 * an error handle. |
884 */ | 916 */ |
885 DART_EXPORT Dart_Handle Dart_NewExternalString32(const uint32_t* codepoints, | 917 DART_EXPORT Dart_Handle Dart_NewExternalString32(const uint32_t* codepoints, |
886 intptr_t length, | 918 intptr_t length, |
887 void* peer, | 919 void* peer, |
(...skipping 433 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1321 | 1353 |
1322 // --- Profiling support ---- | 1354 // --- Profiling support ---- |
1323 | 1355 |
1324 // External pprof support for gathering and dumping symbolic | 1356 // External pprof support for gathering and dumping symbolic |
1325 // information that can be used for better profile reports for | 1357 // information that can be used for better profile reports for |
1326 // dynamically generated code. | 1358 // dynamically generated code. |
1327 DART_EXPORT void Dart_InitPprofSupport(); | 1359 DART_EXPORT void Dart_InitPprofSupport(); |
1328 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); | 1360 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); |
1329 | 1361 |
1330 #endif // INCLUDE_DART_API_H_ | 1362 #endif // INCLUDE_DART_API_H_ |
OLD | NEW |