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 406 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
417 * 'isolate' as the current isolate (see | 417 * 'isolate' as the current isolate (see |
418 * Dart_IsolateInterruptCallback). | 418 * Dart_IsolateInterruptCallback). |
419 * | 419 * |
420 * \param isolate The isolate to be interrupted. | 420 * \param isolate The isolate to be interrupted. |
421 */ | 421 */ |
422 DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate); | 422 DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate); |
423 | 423 |
424 // --- Messages and Ports --- | 424 // --- Messages and Ports --- |
425 | 425 |
426 /** | 426 /** |
427 * Messages are used to communicate between isolates. | |
428 */ | |
429 typedef struct _Dart_Message* Dart_Message; | |
430 | |
431 /** | |
432 * A port is used to send or receive inter-isolate messages | 427 * A port is used to send or receive inter-isolate messages |
433 */ | 428 */ |
434 typedef int64_t Dart_Port; | 429 typedef int64_t Dart_Port; |
435 | 430 |
436 const Dart_Port kNoReplyPort = 0; | 431 /** |
| 432 * A message notification callback. |
| 433 * |
| 434 * This callback allows the embedder to provide an alternate wakeup |
| 435 * mechanism for the delivery of inter-isolate messages. It is the |
| 436 * responsibility of the embedder to call Dart_HandleMessage to |
| 437 * process the message. |
| 438 */ |
| 439 typedef void (*Dart_MessageNotifyCallback)(Dart_Isolate dest_isolate); |
437 | 440 |
438 /** | 441 /** |
439 * A message posting callback. | 442 * Allows embedders to provide an alternative wakeup mechanism for the |
440 * | 443 * delivery of inter-isolate messages. This setting only applies to |
441 * This callback allows the embedder to provide an alternate delivery | 444 * the current isolate. |
442 * mechanism for inter-isolate messages. It is the responsibility of | |
443 * the embedder to call Dart_HandleMessage to process the message. | |
444 * | |
445 * If there is no reply port, then the constant 'kNoReplyPort' is | |
446 * passed as the 'reply_port' parameter. | |
447 * | |
448 * The memory pointed to by 'message' has been allocated by malloc. It | |
449 * is the responsibility of the callback to ensure that free(message) | |
450 * is called once the message has been processed. | |
451 * | |
452 * The callback should return false if it runs into a problem | |
453 * processing this message. | |
454 */ | |
455 typedef bool (*Dart_PostMessageCallback)(Dart_Isolate dest_isolate, | |
456 Dart_Port dest_port_id, | |
457 Dart_Port reply_port_id, | |
458 Dart_Message message); | |
459 // TODO(turnidge): Add a Dart_ReleaseMessage to hide allocation details. | |
460 | |
461 const Dart_Port kCloseAllPorts = 0; | |
462 | |
463 /** | |
464 * A close port callback. | |
465 * | |
466 * This callback allows the embedder to receive notification when a | |
467 * port is closed. The constant 'kCloseAllPorts' is passed as the | |
468 * 'port' parameter when all active ports are being closed at once. | |
469 */ | |
470 typedef void (*Dart_ClosePortCallback)(Dart_Isolate isolate, | |
471 Dart_Port port_id); | |
472 | |
473 /** | |
474 * Allows embedders to provide an alternative mechanism for sending | |
475 * inter-isolate messages. This setting only applies to the current | |
476 * isolate. | |
477 * | 445 * |
478 * Most embedders will only call this function once, before isolate | 446 * Most embedders will only call this function once, before isolate |
479 * execution begins. If this function is called after isolate | 447 * execution begins. If this function is called after isolate |
480 * execution begins, the embedder is responsible for threading issues. | 448 * execution begins, the embedder is responsible for threading issues. |
481 */ | 449 */ |
482 DART_EXPORT void Dart_SetMessageCallbacks( | 450 DART_EXPORT void Dart_SetMessageNotifyCallback( |
483 Dart_PostMessageCallback post_message_callback, | 451 Dart_MessageNotifyCallback message_notify_callback); |
484 Dart_ClosePortCallback close_port_callback); | |
485 // TODO(turnidge): Consider moving this to isolate creation so that it | 452 // TODO(turnidge): Consider moving this to isolate creation so that it |
486 // is impossible to mess up. | 453 // is impossible to mess up. |
487 | 454 |
488 /** | 455 /** |
489 * Handles a message on the current isolate. | 456 * Handles the next pending message for the current isolate. |
490 * | 457 * |
491 * May generate an unhandled exception error. | 458 * May generate an unhandled exception error. |
492 * | 459 * |
493 * Note that this function does not free the memory associated with | |
494 * 'dart_message'. | |
495 * | |
496 * \return A valid handle if no error occurs during the operation. | 460 * \return A valid handle if no error occurs during the operation. |
497 */ | 461 */ |
498 DART_EXPORT Dart_Handle Dart_HandleMessage(Dart_Port dest_port_id, | 462 DART_EXPORT Dart_Handle Dart_HandleMessage(); |
499 Dart_Port reply_port_id, | |
500 Dart_Message dart_message); | |
501 // TODO(turnidge): Revisit memory management of 'dart_message'. | |
502 | 463 |
503 /** | 464 /** |
504 * Processes any incoming messages for the current isolate. | 465 * Processes any incoming messages for the current isolate. |
505 * | 466 * |
506 * This function may only be used when the embedder has not provided | 467 * This function may only be used when the embedder has not provided |
507 * an alternate message delivery mechanism with | 468 * an alternate message delivery mechanism with |
508 * Dart_SetMessageCallbacks. It is provided for convenience. | 469 * Dart_SetMessageCallbacks. It is provided for convenience. |
509 * | 470 * |
510 * This function waits for incoming messages for the current | 471 * This function waits for incoming messages for the current |
511 * isolate. As new messages arrive, they are handled using | 472 * isolate. As new messages arrive, they are handled using |
(...skipping 872 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1384 | 1345 |
1385 // --- Profiling support ---- | 1346 // --- Profiling support ---- |
1386 | 1347 |
1387 // External pprof support for gathering and dumping symbolic | 1348 // External pprof support for gathering and dumping symbolic |
1388 // information that can be used for better profile reports for | 1349 // information that can be used for better profile reports for |
1389 // dynamically generated code. | 1350 // dynamically generated code. |
1390 DART_EXPORT void Dart_InitPprofSupport(); | 1351 DART_EXPORT void Dart_InitPprofSupport(); |
1391 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); | 1352 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); |
1392 | 1353 |
1393 #endif // INCLUDE_DART_API_H_ | 1354 #endif // INCLUDE_DART_API_H_ |
OLD | NEW |