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 * \param current_isolate The isolate being interrupted. | |
257 * | |
258 * \return The embedder returns true if the isolate should continue | |
259 * execution. If the embedder returns false, the isolate will be | |
260 * unwound (currently unimplemented). | |
261 */ | |
262 typedef bool (*Dart_IsolateInterruptCallback)(); | |
263 // TODO(turnidge): Define and implement unwinding. | |
264 | |
265 /** | |
249 * Initializes the VM. | 266 * Initializes the VM. |
250 * | 267 * |
251 * \param callback A function to be called during isolate creation. | 268 * \param create A function to be called during isolate creation. |
252 * See Dart_IsolateCreateCallback. | 269 * See Dart_IsolateCreateCallback. |
270 * \param interrupt A function to be called when an isolate is interrupted. | |
271 * See Dart_IsolateInterruptCallback. | |
253 * | 272 * |
254 * \return True if initialization is successful. | 273 * \return True if initialization is successful. |
255 */ | 274 */ |
256 DART_EXPORT bool Dart_Initialize(Dart_IsolateCreateCallback callback); | 275 DART_EXPORT bool Dart_Initialize(Dart_IsolateCreateCallback create, |
276 Dart_IsolateInterruptCallback interrupt); | |
257 | 277 |
258 /** | 278 /** |
259 * Sets command line flags. Should be called before Dart_Initialize. | 279 * Sets command line flags. Should be called before Dart_Initialize. |
260 * | 280 * |
261 * \param argc The length of the arguments array. | 281 * \param argc The length of the arguments array. |
262 * \param argv An array of arguments. | 282 * \param argv An array of arguments. |
263 * | 283 * |
264 * \return True if VM flags set successfully. | 284 * \return True if VM flags set successfully. |
265 */ | 285 */ |
266 DART_EXPORT bool Dart_SetVMFlags(int argc, const char** argv); | 286 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. | 398 * until the next call to Dart_ExitScope. |
379 * \param size Returns the size of the buffer. | 399 * \param size Returns the size of the buffer. |
380 * | 400 * |
381 * \return A valid handle if no error occurs during the operation. | 401 * \return A valid handle if no error occurs during the operation. |
382 */ | 402 */ |
383 DART_EXPORT Dart_Handle Dart_CreateScriptSnapshot(Dart_Handle library, | 403 DART_EXPORT Dart_Handle Dart_CreateScriptSnapshot(Dart_Handle library, |
384 uint8_t** buffer, | 404 uint8_t** buffer, |
385 intptr_t* size); | 405 intptr_t* size); |
386 | 406 |
387 | 407 |
408 /** | |
409 * Schedules an interrupt for the specified isolate. | |
410 * | |
411 * Note that the interrupt does not occur immediately. In fact, if | |
412 * 'isolate' does not execute any further Dart code, then the | |
413 * interrupt will not occur at all. If and when the isolate is | |
414 * interrupted, the isolate interrupt callback will be invoked with | |
415 * 'isolate' as the current isolate (see | |
416 * Dart_IsolateInterruptCallback). | |
siva
2011/12/17 00:05:38
If Dart_ShutdownIsolate is called by an isolate th
| |
417 * | |
418 * \param isolate The isolate to be interrupted. | |
419 */ | |
420 DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate); | |
421 | |
388 // --- Messages and Ports --- | 422 // --- Messages and Ports --- |
389 | 423 |
390 /** | 424 /** |
391 * Messages are used to communicate between isolates. | 425 * Messages are used to communicate between isolates. |
392 */ | 426 */ |
393 typedef struct _Dart_Message* Dart_Message; | 427 typedef struct _Dart_Message* Dart_Message; |
394 | 428 |
395 /** | 429 /** |
396 * A port is used to send or receive inter-isolate messages | 430 * A port is used to send or receive inter-isolate messages |
397 */ | 431 */ |
(...skipping 467 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
865 /** | 899 /** |
866 * Retrieves the peer pointer associated with an external String. | 900 * Retrieves the peer pointer associated with an external String. |
867 */ | 901 */ |
868 DART_EXPORT Dart_Handle Dart_ExternalStringGetPeer(Dart_Handle object, | 902 DART_EXPORT Dart_Handle Dart_ExternalStringGetPeer(Dart_Handle object, |
869 void** peer); | 903 void** peer); |
870 | 904 |
871 | 905 |
872 /** | 906 /** |
873 * Returns a String which references an external array of 8-bit codepoints. | 907 * Returns a String which references an external array of 8-bit codepoints. |
874 * | 908 * |
875 * \param value An array of 8-bit codepoints. This array must not move. | 909 * \param value An array of 8-bit codepoints. This array must not move. |
876 * \param length The length of the codepoints array. | 910 * \param length The length of the codepoints array. |
877 * \param peer An external pointer to associate with this string. | 911 * \param peer An external pointer to associate with this string. |
878 * \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. |
879 * | 913 * |
880 * \return The String object if no error occurs. Otherwise returns | 914 * \return The String object if no error occurs. Otherwise returns |
881 * an error handle. | 915 * an error handle. |
882 */ | 916 */ |
883 DART_EXPORT Dart_Handle Dart_NewExternalString8(const uint8_t* codepoints, | 917 DART_EXPORT Dart_Handle Dart_NewExternalString8(const uint8_t* codepoints, |
884 intptr_t length, | 918 intptr_t length, |
885 void* peer, | 919 void* peer, |
886 Dart_PeerFinalizer callback); | 920 Dart_PeerFinalizer callback); |
887 | 921 |
888 /** | 922 /** |
889 * Returns a String which references an external array of 16-bit codepoints. | 923 * Returns a String which references an external array of 16-bit codepoints. |
890 * | 924 * |
891 * \param value An array of 16-bit codepoints. This array must not move. | 925 * \param value An array of 16-bit codepoints. This array must not move. |
892 * \param length The length of the codepoints array. | 926 * \param length The length of the codepoints array. |
893 * \param peer An external pointer to associate with this string. | 927 * \param peer An external pointer to associate with this string. |
894 * \param callback A callback to be called when this string is finalized. | 928 * \param callback A callback to be called when this string is finalized. |
895 * | 929 * |
896 * \return The String object if no error occurs. Otherwise returns | 930 * \return The String object if no error occurs. Otherwise returns |
897 * an error handle. | 931 * an error handle. |
898 */ | 932 */ |
899 DART_EXPORT Dart_Handle Dart_NewExternalString16(const uint16_t* codepoints, | 933 DART_EXPORT Dart_Handle Dart_NewExternalString16(const uint16_t* codepoints, |
900 intptr_t length, | 934 intptr_t length, |
901 void* peer, | 935 void* peer, |
902 Dart_PeerFinalizer callback); | 936 Dart_PeerFinalizer callback); |
903 | 937 |
904 /** | 938 /** |
905 * Returns a String which references an external array of 32-bit codepoints. | 939 * Returns a String which references an external array of 32-bit codepoints. |
906 * | 940 * |
907 * \param value An array of 32-bit codepoints. This array must not move. | 941 * \param value An array of 32-bit codepoints. This array must not move. |
908 * \param length The length of the codepoints array. | 942 * \param length The length of the codepoints array. |
909 * \param peer An external pointer to associate with this string. | 943 * \param peer An external pointer to associate with this string. |
910 * \param callback A callback to be called when this string is finalized. | 944 * \param callback A callback to be called when this string is finalized. |
911 * | 945 * |
912 * \return The String object if no error occurs. Otherwise returns | 946 * \return The String object if no error occurs. Otherwise returns |
913 * an error handle. | 947 * an error handle. |
914 */ | 948 */ |
915 DART_EXPORT Dart_Handle Dart_NewExternalString32(const uint32_t* codepoints, | 949 DART_EXPORT Dart_Handle Dart_NewExternalString32(const uint32_t* codepoints, |
916 intptr_t length, | 950 intptr_t length, |
917 void* peer, | 951 void* peer, |
(...skipping 433 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
1351 | 1385 |
1352 // --- Profiling support ---- | 1386 // --- Profiling support ---- |
1353 | 1387 |
1354 // External pprof support for gathering and dumping symbolic | 1388 // External pprof support for gathering and dumping symbolic |
1355 // information that can be used for better profile reports for | 1389 // information that can be used for better profile reports for |
1356 // dynamically generated code. | 1390 // dynamically generated code. |
1357 DART_EXPORT void Dart_InitPprofSupport(); | 1391 DART_EXPORT void Dart_InitPprofSupport(); |
1358 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); | 1392 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); |
1359 | 1393 |
1360 #endif // INCLUDE_DART_API_H_ | 1394 #endif // INCLUDE_DART_API_H_ |
OLD | NEW |