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 371 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
382 * error handle. | 382 * error handle. |
383 */ | 383 */ |
384 DART_EXPORT Dart_Handle Dart_RemoveGcEpilogueCallback( | 384 DART_EXPORT Dart_Handle Dart_RemoveGcEpilogueCallback( |
385 Dart_GcEpilogueCallback callback); | 385 Dart_GcEpilogueCallback callback); |
386 | 386 |
387 // --- Initialization and Globals --- | 387 // --- Initialization and Globals --- |
388 | 388 |
389 /** | 389 /** |
390 * An isolate creation and initialization callback function. | 390 * An isolate creation and initialization callback function. |
391 * | 391 * |
392 * This callback, provided by the embedder, is called when the vm | 392 * This callback, provided by the embedder, is called when an isolate needs |
393 * needs to create an isolate. The callback should create an isolate | 393 * to be created. The callback should create an isolate and load the |
394 * by calling Dart_CreateIsolate and load any scripts required for | 394 * required scripts for execution. |
395 * execution. | |
396 * | 395 * |
397 * When the function returns false, it is the responsibility of this | |
398 * function to ensure that Dart_ShutdownIsolate has been called if | |
399 * required (for example, if the isolate was created successfully by | |
400 * Dart_CreateIsolate() but the root library fails to load | |
401 * successfully, then the function should call Dart_ShutdownIsolate | |
402 * before returning). | |
403 * | |
404 * When the function returns false, the function should set *error to | |
405 * a malloc-allocated buffer containing a useful error message. The | |
406 * caller of this function (the vm) will make sure that the buffer is | |
407 * freed. | |
408 * | |
409 * \param script_uri The uri of the script to load. This uri has been | |
410 * canonicalized by the library tag handler from the parent isolate. | |
411 * The callback is responsible for loading this script by a call to | |
412 * Dart_LoadScript or Dart_LoadScriptFromSnapshot. | |
413 * \param main The name of the main entry point this isolate will | |
414 * eventually run. This is provided for advisory purposes only to | |
415 * improve debugging messages. The main function is not invoked by | |
416 * this function. | |
417 * \param callback_data The callback data which was passed to the | |
418 * parent isolate when it was created by calling Dart_CreateIsolate(). | |
419 * \param error A structure into which the embedder can place a | 396 * \param error A structure into which the embedder can place a |
420 * C string containing an error message in the case of failures. | 397 * C string containing an error message in the case of failures. |
421 * | 398 * |
422 * \return The embedder returns false if the creation and | 399 * \return The embedder returns false if the creation and initialization was not |
423 * initialization was not successful and true if successful. | 400 * successful and true if successful. The embedder is responsible for |
| 401 * maintaining consistency in the case of errors (e.g: isolate is created, |
| 402 * but loading of scripts fails then the embedder should ensure that |
| 403 * Dart_ShutdownIsolate is called on the isolate). |
| 404 * In the case of errors the caller is responsible for freeing the buffer |
| 405 * returned in error containing an error string. |
424 */ | 406 */ |
425 typedef bool (*Dart_IsolateCreateCallback)(const char* script_uri, | 407 typedef bool (*Dart_IsolateCreateCallback)(const char* name_prefix, |
426 const char* main, | |
427 void* callback_data, | 408 void* callback_data, |
428 char** error); | 409 char** error); |
429 | 410 |
430 /** | 411 /** |
431 * An isolate interrupt callback function. | 412 * An isolate interrupt callback function. |
432 * | 413 * |
433 * This callback, provided by the embedder, is called when an isolate | 414 * This callback, provided by the embedder, is called when an isolate |
434 * is interrupted as a result of a call to Dart_InterruptIsolate(). | 415 * is interrupted as a result of a call to Dart_InterruptIsolate(). |
435 * When the callback is called, Dart_CurrentIsolate can be used to | 416 * When the callback is called, Dart_CurrentIsolate can be used to |
436 * figure out which isolate is being interrupted. | 417 * figure out which isolate is being interrupted. |
(...skipping 53 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
490 | 471 |
491 /** | 472 /** |
492 * Creates a new isolate. The new isolate becomes the current isolate. | 473 * Creates a new isolate. The new isolate becomes the current isolate. |
493 * | 474 * |
494 * A snapshot can be used to restore the VM quickly to a saved state | 475 * A snapshot can be used to restore the VM quickly to a saved state |
495 * and is useful for fast startup. If snapshot data is provided, the | 476 * and is useful for fast startup. If snapshot data is provided, the |
496 * isolate will be started using that snapshot data. | 477 * isolate will be started using that snapshot data. |
497 * | 478 * |
498 * Requires there to be no current isolate. | 479 * Requires there to be no current isolate. |
499 * | 480 * |
500 * \param script_uri The name of the script this isolate will load. | |
501 * Provided only for advisory purposes to improve debugging messages. | |
502 * \param main The name of the main entry point this isolate will run. | |
503 * Provided only for advisory purposes to improve debugging messages. | |
504 * \param snapshot A buffer containing a VM snapshot or NULL if no | 481 * \param snapshot A buffer containing a VM snapshot or NULL if no |
505 * snapshot is provided. | 482 * snapshot is provided. |
506 * \param callback_data Embedder data. This data will be passed to | |
507 * the Dart_IsolateCreateCallback when new isolates are spawned from | |
508 * this parent isolate. | |
509 * \param error DOCUMENT | |
510 * | 483 * |
511 * \return The new isolate is returned. May be NULL if an error | 484 * \return The new isolate is returned. May be NULL if an error |
512 * occurs duing isolate initialization. | 485 * occurs duing isolate initialization. |
513 */ | 486 */ |
514 DART_EXPORT Dart_Isolate Dart_CreateIsolate(const char* script_uri, | 487 DART_EXPORT Dart_Isolate Dart_CreateIsolate(const char* name_prefix, |
515 const char* main, | |
516 const uint8_t* snapshot, | 488 const uint8_t* snapshot, |
517 void* callback_data, | 489 void* callback_data, |
518 char** error); | 490 char** error); |
519 // TODO(turnidge): Document behavior when there is already a current | 491 // TODO(turnidge): Document behavior when there is already a current |
520 // isolate. | 492 // isolate. |
521 | 493 |
522 /** | 494 /** |
523 * Shuts down the current isolate. After this call, the current | 495 * Shuts down the current isolate. After this call, the current |
524 * isolate is NULL. | 496 * isolate is NULL. |
525 * | 497 * |
(...skipping 1418 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1944 typedef enum { | 1916 typedef enum { |
1945 kLibraryTag = 0, | 1917 kLibraryTag = 0, |
1946 kImportTag, | 1918 kImportTag, |
1947 kSourceTag, | 1919 kSourceTag, |
1948 kCanonicalizeUrl | 1920 kCanonicalizeUrl |
1949 } Dart_LibraryTag; | 1921 } Dart_LibraryTag; |
1950 | 1922 |
1951 // TODO(turnidge): Document. | 1923 // TODO(turnidge): Document. |
1952 typedef Dart_Handle (*Dart_LibraryTagHandler)(Dart_LibraryTag tag, | 1924 typedef Dart_Handle (*Dart_LibraryTagHandler)(Dart_LibraryTag tag, |
1953 Dart_Handle library, | 1925 Dart_Handle library, |
1954 Dart_Handle url); | 1926 Dart_Handle url, |
| 1927 Dart_Handle import_map); |
1955 | 1928 |
1956 /** | 1929 /** |
1957 * Sets library tag handler for the current isolate. This handler is | 1930 * Set library tag handler for the current isolate. This handler is used to |
1958 * used to handle the various tags encountered while loading libraries | 1931 * handle the various tags encountered while loading libraries or scripts in |
1959 * or scripts in the isolate. | 1932 * the isolate. |
1960 * | 1933 * |
1961 * \param handler Handler code to be used for handling the various tags | 1934 * \param handler Handler code to be used for handling the various tags |
1962 * encountered while loading libraries or scripts in the isolate. | 1935 * encountered while loading libraries or scripts in the isolate. |
1963 * | 1936 * |
1964 * \return If no error occurs, the handler is set for the isolate. | 1937 * \return If no error occurs, the handler is set for the isolate. |
1965 * Otherwise an error handle is returned. | 1938 * Otherwise an error handle is returned. |
1966 * | 1939 * |
1967 * TODO(turnidge): Document. | 1940 * TODO(turnidge): Document. |
1968 */ | 1941 */ |
1969 DART_EXPORT Dart_Handle Dart_SetLibraryTagHandler( | 1942 DART_EXPORT Dart_Handle Dart_SetLibraryTagHandler( |
1970 Dart_LibraryTagHandler handler); | 1943 Dart_LibraryTagHandler handler); |
1971 | 1944 |
1972 /** | 1945 /** |
1973 * Sets the import map for the current isolate. | |
1974 * | |
1975 * The import map is a List of Strings, representing a set of (name, | |
1976 * value) pairs. The import map is used during the resolution of # | |
1977 * directives in source files to implement string interpolation. | |
1978 * | |
1979 * For example, if a source file imports: | |
1980 * | |
1981 * #import('${foo}/dart.html'); | |
1982 * | |
1983 * And the import map is: | |
1984 * | |
1985 * [ "foo", "/home/user" ] | |
1986 * | |
1987 * Then the import would resolve to: | |
1988 * | |
1989 * #import('/home/user/dart.html'); | |
1990 * | |
1991 * \param import_map A List of Strings interpreted as a String to | |
1992 * String mapping. | |
1993 * \return If no error occurs, the import map is set for the isolate. | |
1994 * Otherwise an error handle is returned. | |
1995 */ | |
1996 DART_EXPORT Dart_Handle Dart_SetImportMap(Dart_Handle import_map); | |
1997 | |
1998 /** | |
1999 * Loads the root script for the current isolate. | 1946 * Loads the root script for the current isolate. |
2000 * | 1947 * |
2001 * TODO(turnidge): Document. | 1948 * TODO(turnidge): Document. |
2002 */ | 1949 */ |
2003 DART_EXPORT Dart_Handle Dart_LoadScript(Dart_Handle url, | 1950 DART_EXPORT Dart_Handle Dart_LoadScript(Dart_Handle url, |
2004 Dart_Handle source); | 1951 Dart_Handle source, |
| 1952 Dart_Handle import_map); |
2005 | 1953 |
2006 /** | 1954 /** |
2007 * Loads the root script for current isolate from a snapshot. | 1955 * Loads the root script for current isolate from a snapshot. |
2008 * | 1956 * |
2009 * \param buffer A buffer which contains a snapshot of the script. | 1957 * \param buffer A buffer which contains a snapshot of the script. |
2010 * | 1958 * |
2011 * \return If no error occurs, the Library object corresponding to the root | 1959 * \return If no error occurs, the Library object corresponding to the root |
2012 * script is returned. Otherwise an error handle is returned. | 1960 * script is returned. Otherwise an error handle is returned. |
2013 */ | 1961 **/ |
2014 DART_EXPORT Dart_Handle Dart_LoadScriptFromSnapshot(const uint8_t* buffer); | 1962 DART_EXPORT Dart_Handle Dart_LoadScriptFromSnapshot(const uint8_t* buffer); |
2015 | 1963 |
2016 /** | 1964 /** |
2017 * Gets the library for the root script for the current isolate. | |
2018 * | |
2019 * \return Returns the Library object corresponding to the root script | |
2020 * if it has been set by a successful call to Dart_LoadScript or | |
2021 * Dart_LoadScriptFromSnapshot. Otherwise returns Dart_Null(). | |
2022 */ | |
2023 DART_EXPORT Dart_Handle Dart_RootLibrary(); | |
2024 | |
2025 /** | |
2026 * Forces all loaded classes and functions to be compiled eagerly in | 1965 * Forces all loaded classes and functions to be compiled eagerly in |
2027 * the current isolate.. | 1966 * the current isolate.. |
2028 * | 1967 * |
2029 * TODO(turnidge): Document. | 1968 * TODO(turnidge): Document. |
2030 */ | 1969 */ |
2031 DART_EXPORT Dart_Handle Dart_CompileAll(); | 1970 DART_EXPORT Dart_Handle Dart_CompileAll(); |
2032 | 1971 |
2033 /** | 1972 /** |
2034 * Is this object a Library? | 1973 * Is this object a Library? |
2035 */ | 1974 */ |
2036 DART_EXPORT bool Dart_IsLibrary(Dart_Handle object); | 1975 DART_EXPORT bool Dart_IsLibrary(Dart_Handle object); |
2037 | 1976 |
2038 /** | 1977 /** |
2039 * Lookup a class by name from a Library. | 1978 * Lookup a class by name from a Library. |
2040 * | 1979 * |
2041 * \return If no error occurs, the Library is returned. Otherwise an | 1980 * \return If no error occurs, the Library is returned. Otherwise an |
2042 * error handle is returned. | 1981 * error handle is returned. |
2043 */ | 1982 */ |
2044 DART_EXPORT Dart_Handle Dart_GetClass(Dart_Handle library, Dart_Handle name); | 1983 DART_EXPORT Dart_Handle Dart_GetClass(Dart_Handle library, Dart_Handle name); |
2045 // TODO(turnidge): Consider returning Dart_Null() when the class is | 1984 // TODO(turnidge): Consider returning Dart_Null() when the class is |
2046 // not found to distinguish that from a true error case. | 1985 // not found to distinguish that from a true error case. |
2047 | 1986 |
2048 DART_EXPORT Dart_Handle Dart_LibraryUrl(Dart_Handle library); | 1987 DART_EXPORT Dart_Handle Dart_LibraryUrl(Dart_Handle library); |
2049 | 1988 |
2050 DART_EXPORT Dart_Handle Dart_LookupLibrary(Dart_Handle url); | 1989 DART_EXPORT Dart_Handle Dart_LookupLibrary(Dart_Handle url); |
2051 // TODO(turnidge): Consider returning Dart_Null() when the library is | 1990 // TODO(turnidge): Consider returning Dart_Null() when the library is |
2052 // not found to distinguish that from a true error case. | 1991 // not found to distinguish that from a true error case. |
2053 | 1992 |
2054 DART_EXPORT Dart_Handle Dart_LoadLibrary(Dart_Handle url, | 1993 DART_EXPORT Dart_Handle Dart_LoadLibrary(Dart_Handle url, |
2055 Dart_Handle source); | 1994 Dart_Handle source, |
| 1995 Dart_Handle import_map); |
2056 | 1996 |
2057 | 1997 |
2058 DART_EXPORT Dart_Handle Dart_LibraryImportLibrary(Dart_Handle library, | 1998 DART_EXPORT Dart_Handle Dart_LibraryImportLibrary(Dart_Handle library, |
2059 Dart_Handle import); | 1999 Dart_Handle import); |
2060 | 2000 |
2061 DART_EXPORT Dart_Handle Dart_LoadSource(Dart_Handle library, | 2001 DART_EXPORT Dart_Handle Dart_LoadSource(Dart_Handle library, |
2062 Dart_Handle url, | 2002 Dart_Handle url, |
2063 Dart_Handle source); | 2003 Dart_Handle source); |
2064 // TODO(turnidge): Rename to Dart_LibraryLoadSource? | 2004 // TODO(turnidge): Rename to Dart_LibraryLoadSource? |
2065 | 2005 |
(...skipping 12 matching lines...) Expand all Loading... |
2078 | 2018 |
2079 // --- Profiling support ---- | 2019 // --- Profiling support ---- |
2080 | 2020 |
2081 // External pprof support for gathering and dumping symbolic | 2021 // External pprof support for gathering and dumping symbolic |
2082 // information that can be used for better profile reports for | 2022 // information that can be used for better profile reports for |
2083 // dynamically generated code. | 2023 // dynamically generated code. |
2084 DART_EXPORT void Dart_InitPprofSupport(); | 2024 DART_EXPORT void Dart_InitPprofSupport(); |
2085 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); | 2025 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size); |
2086 | 2026 |
2087 #endif // INCLUDE_DART_API_H_ | 2027 #endif // INCLUDE_DART_API_H_ |
OLD | NEW |