OLD | NEW |
---|---|
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, 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 528 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
539 /** | 539 /** |
540 * Gets the version string for the Dart VM. | 540 * Gets the version string for the Dart VM. |
541 * | 541 * |
542 * The version of the Dart VM can be accessed without initializing the VM. | 542 * The version of the Dart VM can be accessed without initializing the VM. |
543 * | 543 * |
544 * \return The version string for the embedded Dart VM. | 544 * \return The version string for the embedded Dart VM. |
545 */ | 545 */ |
546 DART_EXPORT const char* Dart_VersionString(); | 546 DART_EXPORT const char* Dart_VersionString(); |
547 | 547 |
548 /** | 548 /** |
549 * An isolate is the unit of concurrency in Dart. Each isolate has | |
550 * its own memory and thread of control. No state is shared between | |
551 * isolates. Instead, isolates communicate by message passing. | |
552 * | |
553 * Each thread keeps track of its current isolate, which is the | |
554 * isolate which is ready to execute on the current thread. The | |
555 * current isolate may be NULL, in which case no isolate is ready to | |
556 * execute. Most of the Dart apis require there to be a current | |
557 * isolate in order to function without error. The current isolate is | |
558 * set by any call to Dart_CreateIsolate or Dart_EnterIsolate. | |
559 */ | |
560 typedef struct _Dart_Isolate* Dart_Isolate; | |
561 | |
562 /** | |
549 * An isolate creation and initialization callback function. | 563 * An isolate creation and initialization callback function. |
550 * | 564 * |
551 * This callback, provided by the embedder, is called when the vm | 565 * This callback, provided by the embedder, is called when the vm |
552 * needs to create an isolate. The callback should create an isolate | 566 * needs to create an isolate. The callback should create an isolate |
553 * by calling Dart_CreateIsolate and load any scripts required for | 567 * by calling Dart_CreateIsolate and load any scripts required for |
554 * execution. | 568 * execution. |
555 * | 569 * |
556 * When the function returns false, it is the responsibility of this | 570 * When the function returns false, it is the responsibility of this |
557 * function to ensure that Dart_ShutdownIsolate has been called if | 571 * function to ensure that Dart_ShutdownIsolate has been called if |
558 * required (for example, if the isolate was created successfully by | 572 * required (for example, if the isolate was created successfully by |
559 * Dart_CreateIsolate() but the root library fails to load | 573 * Dart_CreateIsolate() but the root library fails to load |
560 * successfully, then the function should call Dart_ShutdownIsolate | 574 * successfully, then the function should call Dart_ShutdownIsolate |
561 * before returning). | 575 * before returning). |
562 * | 576 * |
563 * When the function returns false, the function should set *error to | 577 * When the function returns false, the function should set *error to |
564 * a malloc-allocated buffer containing a useful error message. The | 578 * a malloc-allocated buffer containing a useful error message. The |
565 * caller of this function (the vm) will make sure that the buffer is | 579 * caller of this function (the vm) will make sure that the buffer is |
566 * freed. | 580 * freed. |
567 * | 581 * |
568 * \param script_uri The uri of the script to load. This uri has been | 582 * \param script_uri The uri of the script to load. This uri has been |
569 * canonicalized by the library tag handler from the parent isolate. | 583 * canonicalized by the library tag handler from the parent isolate. |
570 * The callback is responsible for loading this script by a call to | 584 * The callback is responsible for loading this script by a call to |
571 * Dart_LoadScript or Dart_LoadScriptFromSnapshot. | 585 * Dart_LoadScript or Dart_LoadScriptFromSnapshot. |
572 * \param main The name of the main entry point this isolate will | 586 * \param main The name of the main entry point this isolate will |
573 * eventually run. This is provided for advisory purposes only to | 587 * eventually run. This is provided for advisory purposes only to |
574 * improve debugging messages. The main function is not invoked by | 588 * improve debugging messages. The main function is not invoked by |
575 * this function. | 589 * this function. |
590 * \param unhandled_exc The name of the function to this isolate will | |
591 * call when an unhandled exception is encountered. | |
576 * \param callback_data The callback data which was passed to the | 592 * \param callback_data The callback data which was passed to the |
577 * parent isolate when it was created by calling Dart_CreateIsolate(). | 593 * parent isolate when it was created by calling Dart_CreateIsolate(). |
578 * \param error A structure into which the embedder can place a | 594 * \param error A structure into which the embedder can place a |
579 * C string containing an error message in the case of failures. | 595 * C string containing an error message in the case of failures. |
580 * | 596 * |
581 * \return The embedder returns false if the creation and | 597 * \return The embedder returns false if the creation and |
Anton Muhin
2013/04/08 15:20:17
nit: this doc is not correct any more.
Ivan Posva
2013/04/09 17:38:55
Done.
| |
582 * initialization was not successful and true if successful. | 598 * initialization was not successful and true if successful. |
583 */ | 599 */ |
584 typedef bool (*Dart_IsolateCreateCallback)(const char* script_uri, | 600 typedef Dart_Isolate (*Dart_IsolateCreateCallback)(const char* script_uri, |
585 const char* main, | 601 const char* main, |
586 void* callback_data, | 602 void* callback_data, |
587 char** error); | 603 char** error); |
588 | 604 |
589 /** | 605 /** |
590 * An isolate interrupt callback function. | 606 * An isolate interrupt callback function. |
591 * | 607 * |
592 * This callback, provided by the embedder, is called when an isolate | 608 * This callback, provided by the embedder, is called when an isolate |
593 * is interrupted as a result of a call to Dart_InterruptIsolate(). | 609 * is interrupted as a result of a call to Dart_InterruptIsolate(). |
594 * When the callback is called, Dart_CurrentIsolate can be used to | 610 * When the callback is called, Dart_CurrentIsolate can be used to |
595 * figure out which isolate is being interrupted. | 611 * figure out which isolate is being interrupted. |
596 * | 612 * |
597 * \return The embedder returns true if the isolate should continue | 613 * \return The embedder returns true if the isolate should continue |
(...skipping 75 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
673 DART_EXPORT bool Dart_SetVMFlags(int argc, const char** argv); | 689 DART_EXPORT bool Dart_SetVMFlags(int argc, const char** argv); |
674 | 690 |
675 /** | 691 /** |
676 * Returns true if the named VM flag is set. | 692 * Returns true if the named VM flag is set. |
677 */ | 693 */ |
678 DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name); | 694 DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name); |
679 | 695 |
680 // --- Isolates --- | 696 // --- Isolates --- |
681 | 697 |
682 /** | 698 /** |
683 * An isolate is the unit of concurrency in Dart. Each isolate has | |
684 * its own memory and thread of control. No state is shared between | |
685 * isolates. Instead, isolates communicate by message passing. | |
686 * | |
687 * Each thread keeps track of its current isolate, which is the | |
688 * isolate which is ready to execute on the current thread. The | |
689 * current isolate may be NULL, in which case no isolate is ready to | |
690 * execute. Most of the Dart apis require there to be a current | |
691 * isolate in order to function without error. The current isolate is | |
692 * set by any call to Dart_CreateIsolate or Dart_EnterIsolate. | |
693 */ | |
694 typedef struct _Dart_Isolate* Dart_Isolate; | |
695 | |
696 /** | |
697 * Creates a new isolate. The new isolate becomes the current isolate. | 699 * Creates a new isolate. The new isolate becomes the current isolate. |
698 * | 700 * |
699 * A snapshot can be used to restore the VM quickly to a saved state | 701 * A snapshot can be used to restore the VM quickly to a saved state |
700 * and is useful for fast startup. If snapshot data is provided, the | 702 * and is useful for fast startup. If snapshot data is provided, the |
701 * isolate will be started using that snapshot data. | 703 * isolate will be started using that snapshot data. |
702 * | 704 * |
703 * Requires there to be no current isolate. | 705 * Requires there to be no current isolate. |
704 * | 706 * |
705 * \param script_uri The name of the script this isolate will load. | 707 * \param script_uri The name of the script this isolate will load. |
706 * Provided only for advisory purposes to improve debugging messages. | 708 * Provided only for advisory purposes to improve debugging messages. |
(...skipping 113 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
820 * 'isolate' does not execute any further Dart code, then the | 822 * 'isolate' does not execute any further Dart code, then the |
821 * interrupt will not occur at all. If and when the isolate is | 823 * interrupt will not occur at all. If and when the isolate is |
822 * interrupted, the isolate interrupt callback will be invoked with | 824 * interrupted, the isolate interrupt callback will be invoked with |
823 * 'isolate' as the current isolate (see | 825 * 'isolate' as the current isolate (see |
824 * Dart_IsolateInterruptCallback). | 826 * Dart_IsolateInterruptCallback). |
825 * | 827 * |
826 * \param isolate The isolate to be interrupted. | 828 * \param isolate The isolate to be interrupted. |
827 */ | 829 */ |
828 DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate); | 830 DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate); |
829 | 831 |
832 | |
833 /** | |
834 * Make isolate runnable. | |
835 * | |
836 * When isolates are spawned this function is used to indicate that | |
837 * the creation and initialization (including script loading) of the | |
838 * isolate is complete and the isolate can start. | |
839 * This function does not expect there to be a current isolate. | |
840 * | |
841 * \param isolate The isolate to be made runnable. | |
842 */ | |
843 DART_EXPORT bool Dart_IsolateMakeRunnable(Dart_Isolate isolate); | |
Anton Muhin
2013/04/08 15:20:17
any restriction on thread affinity?
Ivan Posva
2013/04/09 17:38:55
Not sure I understand the question, but this will
Anton Muhin
2013/04/09 17:45:12
Sorry for not being clear, I was curious if there
Ivan Posva
2013/04/09 18:19:48
The Dart_IsolateMakeRunnable should be callable on
| |
844 | |
845 | |
830 // --- Messages and Ports --- | 846 // --- Messages and Ports --- |
831 | 847 |
832 /** | 848 /** |
833 * A port is used to send or receive inter-isolate messages | 849 * A port is used to send or receive inter-isolate messages |
834 */ | 850 */ |
835 typedef int64_t Dart_Port; | 851 typedef int64_t Dart_Port; |
836 | 852 |
837 /** | 853 /** |
838 * ILLEGAL_PORT is a port number guaranteed never to be associated with a valid | 854 * ILLEGAL_PORT is a port number guaranteed never to be associated with a valid |
839 * port. | 855 * port. |
(...skipping 1717 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
2557 * | 2573 * |
2558 * \param object An object. | 2574 * \param object An object. |
2559 * \param peer A value to store in the peer field. | 2575 * \param peer A value to store in the peer field. |
2560 * | 2576 * |
2561 * \return Returns an error if 'object' is a subtype of Null, num, or | 2577 * \return Returns an error if 'object' is a subtype of Null, num, or |
2562 * bool. | 2578 * bool. |
2563 */ | 2579 */ |
2564 DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer); | 2580 DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer); |
2565 | 2581 |
2566 #endif // INCLUDE_DART_API_H_ | 2582 #endif // INCLUDE_DART_API_H_ |
OLD | NEW |