dart_api.h 146 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185
  1. /*
  2. * Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file
  3. * for details. All rights reserved. Use of this source code is governed by a
  4. * BSD-style license that can be found in the LICENSE file.
  5. */
  6. #ifndef RUNTIME_INCLUDE_DART_API_H_
  7. #define RUNTIME_INCLUDE_DART_API_H_
  8. /** \mainpage Dart Embedding API Reference
  9. *
  10. * This reference describes the Dart Embedding API, which is used to embed the
  11. * Dart Virtual Machine within C/C++ applications.
  12. *
  13. * This reference is generated from the header include/dart_api.h.
  14. */
  15. /* __STDC_FORMAT_MACROS has to be defined before including <inttypes.h> to
  16. * enable platform independent printf format specifiers. */
  17. #ifndef __STDC_FORMAT_MACROS
  18. #define __STDC_FORMAT_MACROS
  19. #endif
  20. #include <assert.h>
  21. #include <inttypes.h>
  22. #include <stdbool.h>
  23. #if defined(__Fuchsia__)
  24. #include <zircon/types.h>
  25. #endif
  26. #ifdef __cplusplus
  27. #define DART_EXTERN_C extern "C"
  28. #else
  29. #define DART_EXTERN_C extern
  30. #endif
  31. #if defined(__CYGWIN__)
  32. #error Tool chain and platform not supported.
  33. #elif defined(_WIN32)
  34. #if defined(DART_SHARED_LIB)
  35. #define DART_EXPORT DART_EXTERN_C __declspec(dllexport)
  36. #else
  37. #define DART_EXPORT DART_EXTERN_C
  38. #endif
  39. #else
  40. #if __GNUC__ >= 4
  41. #if defined(DART_SHARED_LIB)
  42. #define DART_EXPORT \
  43. DART_EXTERN_C __attribute__((visibility("default"))) __attribute((used))
  44. #else
  45. #define DART_EXPORT DART_EXTERN_C
  46. #endif
  47. #else
  48. #error Tool chain not supported.
  49. #endif
  50. #endif
  51. #if __GNUC__
  52. #define DART_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
  53. #elif _MSC_VER
  54. #define DART_WARN_UNUSED_RESULT _Check_return_
  55. #else
  56. #define DART_WARN_UNUSED_RESULT
  57. #endif
  58. /*
  59. * =======
  60. * Handles
  61. * =======
  62. */
  63. /**
  64. * An isolate is the unit of concurrency in Dart. Each isolate has
  65. * its own memory and thread of control. No state is shared between
  66. * isolates. Instead, isolates communicate by message passing.
  67. *
  68. * Each thread keeps track of its current isolate, which is the
  69. * isolate which is ready to execute on the current thread. The
  70. * current isolate may be NULL, in which case no isolate is ready to
  71. * execute. Most of the Dart apis require there to be a current
  72. * isolate in order to function without error. The current isolate is
  73. * set by any call to Dart_CreateIsolateGroup or Dart_EnterIsolate.
  74. */
  75. typedef struct _Dart_Isolate* Dart_Isolate;
  76. typedef struct _Dart_IsolateGroup* Dart_IsolateGroup;
  77. /**
  78. * An object reference managed by the Dart VM garbage collector.
  79. *
  80. * Because the garbage collector may move objects, it is unsafe to
  81. * refer to objects directly. Instead, we refer to objects through
  82. * handles, which are known to the garbage collector and updated
  83. * automatically when the object is moved. Handles should be passed
  84. * by value (except in cases like out-parameters) and should never be
  85. * allocated on the heap.
  86. *
  87. * Most functions in the Dart Embedding API return a handle. When a
  88. * function completes normally, this will be a valid handle to an
  89. * object in the Dart VM heap. This handle may represent the result of
  90. * the operation or it may be a special valid handle used merely to
  91. * indicate successful completion. Note that a valid handle may in
  92. * some cases refer to the null object.
  93. *
  94. * --- Error handles ---
  95. *
  96. * When a function encounters a problem that prevents it from
  97. * completing normally, it returns an error handle (See Dart_IsError).
  98. * An error handle has an associated error message that gives more
  99. * details about the problem (See Dart_GetError).
  100. *
  101. * There are four kinds of error handles that can be produced,
  102. * depending on what goes wrong:
  103. *
  104. * - Api error handles are produced when an api function is misused.
  105. * This happens when a Dart embedding api function is called with
  106. * invalid arguments or in an invalid context.
  107. *
  108. * - Unhandled exception error handles are produced when, during the
  109. * execution of Dart code, an exception is thrown but not caught.
  110. * Prototypically this would occur during a call to Dart_Invoke, but
  111. * it can occur in any function which triggers the execution of Dart
  112. * code (for example, Dart_ToString).
  113. *
  114. * An unhandled exception error provides access to an exception and
  115. * stacktrace via the functions Dart_ErrorGetException and
  116. * Dart_ErrorGetStackTrace.
  117. *
  118. * - Compilation error handles are produced when, during the execution
  119. * of Dart code, a compile-time error occurs. As above, this can
  120. * occur in any function which triggers the execution of Dart code.
  121. *
  122. * - Fatal error handles are produced when the system wants to shut
  123. * down the current isolate.
  124. *
  125. * --- Propagating errors ---
  126. *
  127. * When an error handle is returned from the top level invocation of
  128. * Dart code in a program, the embedder must handle the error as they
  129. * see fit. Often, the embedder will print the error message produced
  130. * by Dart_Error and exit the program.
  131. *
  132. * When an error is returned while in the body of a native function,
  133. * it can be propagated up the call stack by calling
  134. * Dart_PropagateError, Dart_SetReturnValue, or Dart_ThrowException.
  135. * Errors should be propagated unless there is a specific reason not
  136. * to. If an error is not propagated then it is ignored. For
  137. * example, if an unhandled exception error is ignored, that
  138. * effectively "catches" the unhandled exception. Fatal errors must
  139. * always be propagated.
  140. *
  141. * When an error is propagated, any current scopes created by
  142. * Dart_EnterScope will be exited.
  143. *
  144. * Using Dart_SetReturnValue to propagate an exception is somewhat
  145. * more convenient than using Dart_PropagateError, and should be
  146. * preferred for reasons discussed below.
  147. *
  148. * Dart_PropagateError and Dart_ThrowException do not return. Instead
  149. * they transfer control non-locally using a setjmp-like mechanism.
  150. * This can be inconvenient if you have resources that you need to
  151. * clean up before propagating the error.
  152. *
  153. * When relying on Dart_PropagateError, we often return error handles
  154. * rather than propagating them from helper functions. Consider the
  155. * following contrived example:
  156. *
  157. * 1 Dart_Handle isLongStringHelper(Dart_Handle arg) {
  158. * 2 intptr_t* length = 0;
  159. * 3 result = Dart_StringLength(arg, &length);
  160. * 4 if (Dart_IsError(result)) {
  161. * 5 return result;
  162. * 6 }
  163. * 7 return Dart_NewBoolean(length > 100);
  164. * 8 }
  165. * 9
  166. * 10 void NativeFunction_isLongString(Dart_NativeArguments args) {
  167. * 11 Dart_EnterScope();
  168. * 12 AllocateMyResource();
  169. * 13 Dart_Handle arg = Dart_GetNativeArgument(args, 0);
  170. * 14 Dart_Handle result = isLongStringHelper(arg);
  171. * 15 if (Dart_IsError(result)) {
  172. * 16 FreeMyResource();
  173. * 17 Dart_PropagateError(result);
  174. * 18 abort(); // will not reach here
  175. * 19 }
  176. * 20 Dart_SetReturnValue(result);
  177. * 21 FreeMyResource();
  178. * 22 Dart_ExitScope();
  179. * 23 }
  180. *
  181. * In this example, we have a native function which calls a helper
  182. * function to do its work. On line 5, the helper function could call
  183. * Dart_PropagateError, but that would not give the native function a
  184. * chance to call FreeMyResource(), causing a leak. Instead, the
  185. * helper function returns the error handle to the caller, giving the
  186. * caller a chance to clean up before propagating the error handle.
  187. *
  188. * When an error is propagated by calling Dart_SetReturnValue, the
  189. * native function will be allowed to complete normally and then the
  190. * exception will be propagated only once the native call
  191. * returns. This can be convenient, as it allows the C code to clean
  192. * up normally.
  193. *
  194. * The example can be written more simply using Dart_SetReturnValue to
  195. * propagate the error.
  196. *
  197. * 1 Dart_Handle isLongStringHelper(Dart_Handle arg) {
  198. * 2 intptr_t* length = 0;
  199. * 3 result = Dart_StringLength(arg, &length);
  200. * 4 if (Dart_IsError(result)) {
  201. * 5 return result
  202. * 6 }
  203. * 7 return Dart_NewBoolean(length > 100);
  204. * 8 }
  205. * 9
  206. * 10 void NativeFunction_isLongString(Dart_NativeArguments args) {
  207. * 11 Dart_EnterScope();
  208. * 12 AllocateMyResource();
  209. * 13 Dart_Handle arg = Dart_GetNativeArgument(args, 0);
  210. * 14 Dart_SetReturnValue(isLongStringHelper(arg));
  211. * 15 FreeMyResource();
  212. * 16 Dart_ExitScope();
  213. * 17 }
  214. *
  215. * In this example, the call to Dart_SetReturnValue on line 14 will
  216. * either return the normal return value or the error (potentially
  217. * generated on line 3). The call to FreeMyResource on line 15 will
  218. * execute in either case.
  219. *
  220. * --- Local and persistent handles ---
  221. *
  222. * Local handles are allocated within the current scope (see
  223. * Dart_EnterScope) and go away when the current scope exits. Unless
  224. * otherwise indicated, callers should assume that all functions in
  225. * the Dart embedding api return local handles.
  226. *
  227. * Persistent handles are allocated within the current isolate. They
  228. * can be used to store objects across scopes. Persistent handles have
  229. * the lifetime of the current isolate unless they are explicitly
  230. * deallocated (see Dart_DeletePersistentHandle).
  231. * The type Dart_Handle represents a handle (both local and persistent).
  232. * The type Dart_PersistentHandle is a Dart_Handle and it is used to
  233. * document that a persistent handle is expected as a parameter to a call
  234. * or the return value from a call is a persistent handle.
  235. *
  236. * FinalizableHandles are persistent handles which are auto deleted when
  237. * the object is garbage collected. It is never safe to use these handles
  238. * unless you know the object is still reachable.
  239. *
  240. * WeakPersistentHandles are persistent handles which are automatically set
  241. * to point Dart_Null when the object is garbage collected. They are not auto
  242. * deleted, so it is safe to use them after the object has become unreachable.
  243. */
  244. typedef struct _Dart_Handle* Dart_Handle;
  245. typedef Dart_Handle Dart_PersistentHandle;
  246. typedef struct _Dart_WeakPersistentHandle* Dart_WeakPersistentHandle;
  247. typedef struct _Dart_FinalizableHandle* Dart_FinalizableHandle;
  248. // These structs are versioned by DART_API_DL_MAJOR_VERSION, bump the
  249. // version when changing this struct.
  250. typedef void (*Dart_HandleFinalizer)(void* isolate_callback_data, void* peer);
  251. /**
  252. * Is this an error handle?
  253. *
  254. * Requires there to be a current isolate.
  255. */
  256. DART_EXPORT bool Dart_IsError(Dart_Handle handle);
  257. /**
  258. * Is this an api error handle?
  259. *
  260. * Api error handles are produced when an api function is misused.
  261. * This happens when a Dart embedding api function is called with
  262. * invalid arguments or in an invalid context.
  263. *
  264. * Requires there to be a current isolate.
  265. */
  266. DART_EXPORT bool Dart_IsApiError(Dart_Handle handle);
  267. /**
  268. * Is this an unhandled exception error handle?
  269. *
  270. * Unhandled exception error handles are produced when, during the
  271. * execution of Dart code, an exception is thrown but not caught.
  272. * This can occur in any function which triggers the execution of Dart
  273. * code.
  274. *
  275. * See Dart_ErrorGetException and Dart_ErrorGetStackTrace.
  276. *
  277. * Requires there to be a current isolate.
  278. */
  279. DART_EXPORT bool Dart_IsUnhandledExceptionError(Dart_Handle handle);
  280. /**
  281. * Is this a compilation error handle?
  282. *
  283. * Compilation error handles are produced when, during the execution
  284. * of Dart code, a compile-time error occurs. This can occur in any
  285. * function which triggers the execution of Dart code.
  286. *
  287. * Requires there to be a current isolate.
  288. */
  289. DART_EXPORT bool Dart_IsCompilationError(Dart_Handle handle);
  290. /**
  291. * Is this a fatal error handle?
  292. *
  293. * Fatal error handles are produced when the system wants to shut down
  294. * the current isolate.
  295. *
  296. * Requires there to be a current isolate.
  297. */
  298. DART_EXPORT bool Dart_IsFatalError(Dart_Handle handle);
  299. /**
  300. * Gets the error message from an error handle.
  301. *
  302. * Requires there to be a current isolate.
  303. *
  304. * \return A C string containing an error message if the handle is
  305. * error. An empty C string ("") if the handle is valid. This C
  306. * String is scope allocated and is only valid until the next call
  307. * to Dart_ExitScope.
  308. */
  309. DART_EXPORT const char* Dart_GetError(Dart_Handle handle);
  310. /**
  311. * Is this an error handle for an unhandled exception?
  312. */
  313. DART_EXPORT bool Dart_ErrorHasException(Dart_Handle handle);
  314. /**
  315. * Gets the exception Object from an unhandled exception error handle.
  316. */
  317. DART_EXPORT Dart_Handle Dart_ErrorGetException(Dart_Handle handle);
  318. /**
  319. * Gets the stack trace Object from an unhandled exception error handle.
  320. */
  321. DART_EXPORT Dart_Handle Dart_ErrorGetStackTrace(Dart_Handle handle);
  322. /**
  323. * Produces an api error handle with the provided error message.
  324. *
  325. * Requires there to be a current isolate.
  326. *
  327. * \param error the error message.
  328. */
  329. DART_EXPORT Dart_Handle Dart_NewApiError(const char* error);
  330. DART_EXPORT Dart_Handle Dart_NewCompilationError(const char* error);
  331. /**
  332. * Produces a new unhandled exception error handle.
  333. *
  334. * Requires there to be a current isolate.
  335. *
  336. * \param exception An instance of a Dart object to be thrown or
  337. * an ApiError or CompilationError handle.
  338. * When an ApiError or CompilationError handle is passed in
  339. * a string object of the error message is created and it becomes
  340. * the Dart object to be thrown.
  341. */
  342. DART_EXPORT Dart_Handle Dart_NewUnhandledExceptionError(Dart_Handle exception);
  343. /**
  344. * Propagates an error.
  345. *
  346. * If the provided handle is an unhandled exception error, this
  347. * function will cause the unhandled exception to be rethrown. This
  348. * will proceed in the standard way, walking up Dart frames until an
  349. * appropriate 'catch' block is found, executing 'finally' blocks,
  350. * etc.
  351. *
  352. * If the error is not an unhandled exception error, we will unwind
  353. * the stack to the next C frame. Intervening Dart frames will be
  354. * discarded; specifically, 'finally' blocks will not execute. This
  355. * is the standard way that compilation errors (and the like) are
  356. * handled by the Dart runtime.
  357. *
  358. * In either case, when an error is propagated any current scopes
  359. * created by Dart_EnterScope will be exited.
  360. *
  361. * See the additional discussion under "Propagating Errors" at the
  362. * beginning of this file.
  363. *
  364. * \param handle An error handle (See Dart_IsError)
  365. *
  366. * On success, this function does not return. On failure, the
  367. * process is terminated.
  368. */
  369. DART_EXPORT void Dart_PropagateError(Dart_Handle handle);
  370. /**
  371. * Converts an object to a string.
  372. *
  373. * May generate an unhandled exception error.
  374. *
  375. * \return The converted string if no error occurs during
  376. * the conversion. If an error does occur, an error handle is
  377. * returned.
  378. */
  379. DART_EXPORT Dart_Handle Dart_ToString(Dart_Handle object);
  380. /**
  381. * Checks to see if two handles refer to identically equal objects.
  382. *
  383. * If both handles refer to instances, this is equivalent to using the top-level
  384. * function identical() from dart:core. Otherwise, returns whether the two
  385. * argument handles refer to the same object.
  386. *
  387. * \param obj1 An object to be compared.
  388. * \param obj2 An object to be compared.
  389. *
  390. * \return True if the objects are identically equal. False otherwise.
  391. */
  392. DART_EXPORT bool Dart_IdentityEquals(Dart_Handle obj1, Dart_Handle obj2);
  393. /**
  394. * Allocates a handle in the current scope from a persistent handle.
  395. */
  396. DART_EXPORT Dart_Handle Dart_HandleFromPersistent(Dart_PersistentHandle object);
  397. /**
  398. * Allocates a handle in the current scope from a weak persistent handle.
  399. *
  400. * This will be a handle to Dart_Null if the object has been garbage collected.
  401. */
  402. DART_EXPORT Dart_Handle
  403. Dart_HandleFromWeakPersistent(Dart_WeakPersistentHandle object);
  404. /**
  405. * Allocates a persistent handle for an object.
  406. *
  407. * This handle has the lifetime of the current isolate unless it is
  408. * explicitly deallocated by calling Dart_DeletePersistentHandle.
  409. *
  410. * Requires there to be a current isolate.
  411. */
  412. DART_EXPORT Dart_PersistentHandle Dart_NewPersistentHandle(Dart_Handle object);
  413. /**
  414. * Assign value of local handle to a persistent handle.
  415. *
  416. * Requires there to be a current isolate.
  417. *
  418. * \param obj1 A persistent handle whose value needs to be set.
  419. * \param obj2 An object whose value needs to be set to the persistent handle.
  420. */
  421. DART_EXPORT void Dart_SetPersistentHandle(Dart_PersistentHandle obj1,
  422. Dart_Handle obj2);
  423. /**
  424. * Deallocates a persistent handle.
  425. *
  426. * Requires there to be a current isolate group.
  427. */
  428. DART_EXPORT void Dart_DeletePersistentHandle(Dart_PersistentHandle object);
  429. /**
  430. * Allocates a weak persistent handle for an object.
  431. *
  432. * This handle has the lifetime of the current isolate. The handle can also be
  433. * explicitly deallocated by calling Dart_DeleteWeakPersistentHandle.
  434. *
  435. * If the object becomes unreachable the callback is invoked with the peer as
  436. * argument. The callback can be executed on any thread, will have a current
  437. * isolate group, but will not have a current isolate. The callback can only
  438. * call Dart_DeletePersistentHandle or Dart_DeleteWeakPersistentHandle. This
  439. * gives the embedder the ability to cleanup data associated with the object.
  440. * The handle will point to the Dart_Null object after the finalizer has been
  441. * run. It is illegal to call into the VM with any other Dart_* functions from
  442. * the callback. If the handle is deleted before the object becomes
  443. * unreachable, the callback is never invoked.
  444. *
  445. * Requires there to be a current isolate.
  446. *
  447. * \param object An object with identity.
  448. * \param peer A pointer to a native object or NULL. This value is
  449. * provided to callback when it is invoked.
  450. * \param external_allocation_size The number of externally allocated
  451. * bytes for peer. Used to inform the garbage collector.
  452. * \param callback A function pointer that will be invoked sometime
  453. * after the object is garbage collected, unless the handle has been deleted.
  454. * A valid callback needs to be specified it cannot be NULL.
  455. *
  456. * \return The weak persistent handle or NULL. NULL is returned in case of bad
  457. * parameters.
  458. */
  459. DART_EXPORT Dart_WeakPersistentHandle
  460. Dart_NewWeakPersistentHandle(Dart_Handle object,
  461. void* peer,
  462. intptr_t external_allocation_size,
  463. Dart_HandleFinalizer callback);
  464. /**
  465. * Deletes the given weak persistent [object] handle.
  466. *
  467. * Requires there to be a current isolate group.
  468. */
  469. DART_EXPORT void Dart_DeleteWeakPersistentHandle(
  470. Dart_WeakPersistentHandle object);
  471. /**
  472. * Updates the external memory size for the given weak persistent handle.
  473. *
  474. * May trigger garbage collection.
  475. */
  476. DART_EXPORT void Dart_UpdateExternalSize(Dart_WeakPersistentHandle object,
  477. intptr_t external_allocation_size);
  478. /**
  479. * Allocates a finalizable handle for an object.
  480. *
  481. * This handle has the lifetime of the current isolate group unless the object
  482. * pointed to by the handle is garbage collected, in this case the VM
  483. * automatically deletes the handle after invoking the callback associated
  484. * with the handle. The handle can also be explicitly deallocated by
  485. * calling Dart_DeleteFinalizableHandle.
  486. *
  487. * If the object becomes unreachable the callback is invoked with the
  488. * the peer as argument. The callback can be executed on any thread, will have
  489. * an isolate group, but will not have a current isolate. The callback can only
  490. * call Dart_DeletePersistentHandle or Dart_DeleteWeakPersistentHandle.
  491. * This gives the embedder the ability to cleanup data associated with the
  492. * object and clear out any cached references to the handle. All references to
  493. * this handle after the callback will be invalid. It is illegal to call into
  494. * the VM with any other Dart_* functions from the callback. If the handle is
  495. * deleted before the object becomes unreachable, the callback is never
  496. * invoked.
  497. *
  498. * Requires there to be a current isolate.
  499. *
  500. * \param object An object with identity.
  501. * \param peer A pointer to a native object or NULL. This value is
  502. * provided to callback when it is invoked.
  503. * \param external_allocation_size The number of externally allocated
  504. * bytes for peer. Used to inform the garbage collector.
  505. * \param callback A function pointer that will be invoked sometime
  506. * after the object is garbage collected, unless the handle has been deleted.
  507. * A valid callback needs to be specified it cannot be NULL.
  508. *
  509. * \return The finalizable handle or NULL. NULL is returned in case of bad
  510. * parameters.
  511. */
  512. DART_EXPORT Dart_FinalizableHandle
  513. Dart_NewFinalizableHandle(Dart_Handle object,
  514. void* peer,
  515. intptr_t external_allocation_size,
  516. Dart_HandleFinalizer callback);
  517. /**
  518. * Deletes the given finalizable [object] handle.
  519. *
  520. * The caller has to provide the actual Dart object the handle was created from
  521. * to prove the object (and therefore the finalizable handle) is still alive.
  522. *
  523. * Requires there to be a current isolate.
  524. */
  525. DART_EXPORT void Dart_DeleteFinalizableHandle(Dart_FinalizableHandle object,
  526. Dart_Handle strong_ref_to_object);
  527. /**
  528. * Updates the external memory size for the given finalizable handle.
  529. *
  530. * The caller has to provide the actual Dart object the handle was created from
  531. * to prove the object (and therefore the finalizable handle) is still alive.
  532. *
  533. * May trigger garbage collection.
  534. */
  535. DART_EXPORT void Dart_UpdateFinalizableExternalSize(
  536. Dart_FinalizableHandle object,
  537. Dart_Handle strong_ref_to_object,
  538. intptr_t external_allocation_size);
  539. /*
  540. * ==========================
  541. * Initialization and Globals
  542. * ==========================
  543. */
  544. /**
  545. * Gets the version string for the Dart VM.
  546. *
  547. * The version of the Dart VM can be accessed without initializing the VM.
  548. *
  549. * \return The version string for the embedded Dart VM.
  550. */
  551. DART_EXPORT const char* Dart_VersionString(void);
  552. /**
  553. * Isolate specific flags are set when creating a new isolate using the
  554. * Dart_IsolateFlags structure.
  555. *
  556. * Current version of flags is encoded in a 32-bit integer with 16 bits used
  557. * for each part.
  558. */
  559. #define DART_FLAGS_CURRENT_VERSION (0x0000000c)
  560. typedef struct {
  561. int32_t version;
  562. bool enable_asserts;
  563. bool use_field_guards;
  564. bool use_osr;
  565. bool obfuscate;
  566. bool load_vmservice_library;
  567. bool copy_parent_code;
  568. bool null_safety;
  569. bool is_system_isolate;
  570. bool snapshot_is_dontneed_safe;
  571. bool branch_coverage;
  572. } Dart_IsolateFlags;
  573. /**
  574. * Initialize Dart_IsolateFlags with correct version and default values.
  575. */
  576. DART_EXPORT void Dart_IsolateFlagsInitialize(Dart_IsolateFlags* flags);
  577. /**
  578. * An isolate creation and initialization callback function.
  579. *
  580. * This callback, provided by the embedder, is called when the VM
  581. * needs to create an isolate. The callback should create an isolate
  582. * by calling Dart_CreateIsolateGroup and load any scripts required for
  583. * execution.
  584. *
  585. * This callback may be called on a different thread than the one
  586. * running the parent isolate.
  587. *
  588. * When the function returns NULL, it is the responsibility of this
  589. * function to ensure that Dart_ShutdownIsolate has been called if
  590. * required (for example, if the isolate was created successfully by
  591. * Dart_CreateIsolateGroup() but the root library fails to load
  592. * successfully, then the function should call Dart_ShutdownIsolate
  593. * before returning).
  594. *
  595. * When the function returns NULL, the function should set *error to
  596. * a malloc-allocated buffer containing a useful error message. The
  597. * caller of this function (the VM) will make sure that the buffer is
  598. * freed.
  599. *
  600. * \param script_uri The uri of the main source file or snapshot to load.
  601. * Either the URI of the parent isolate set in Dart_CreateIsolateGroup for
  602. * Isolate.spawn, or the argument to Isolate.spawnUri canonicalized by the
  603. * library tag handler of the parent isolate.
  604. * The callback is responsible for loading the program by a call to
  605. * Dart_LoadScriptFromKernel.
  606. * \param main The name of the main entry point this isolate will
  607. * eventually run. This is provided for advisory purposes only to
  608. * improve debugging messages. The main function is not invoked by
  609. * this function.
  610. * \param package_root Ignored.
  611. * \param package_config Uri of the package configuration file (either in format
  612. * of .packages or .dart_tool/package_config.json) for this isolate
  613. * to resolve package imports against. If this parameter is not passed the
  614. * package resolution of the parent isolate should be used.
  615. * \param flags Default flags for this isolate being spawned. Either inherited
  616. * from the spawning isolate or passed as parameters when spawning the
  617. * isolate from Dart code.
  618. * \param isolate_data The isolate data which was passed to the
  619. * parent isolate when it was created by calling Dart_CreateIsolateGroup().
  620. * \param error A structure into which the embedder can place a
  621. * C string containing an error message in the case of failures.
  622. *
  623. * \return The embedder returns NULL if the creation and
  624. * initialization was not successful and the isolate if successful.
  625. */
  626. typedef Dart_Isolate (*Dart_IsolateGroupCreateCallback)(
  627. const char* script_uri,
  628. const char* main,
  629. const char* package_root,
  630. const char* package_config,
  631. Dart_IsolateFlags* flags,
  632. void* isolate_data,
  633. char** error);
  634. /**
  635. * An isolate initialization callback function.
  636. *
  637. * This callback, provided by the embedder, is called when the VM has created an
  638. * isolate within an existing isolate group (i.e. from the same source as an
  639. * existing isolate).
  640. *
  641. * The callback should setup native resolvers and might want to set a custom
  642. * message handler via [Dart_SetMessageNotifyCallback] and mark the isolate as
  643. * runnable.
  644. *
  645. * This callback may be called on a different thread than the one
  646. * running the parent isolate.
  647. *
  648. * When the function returns `false`, it is the responsibility of this
  649. * function to ensure that `Dart_ShutdownIsolate` has been called.
  650. *
  651. * When the function returns `false`, the function should set *error to
  652. * a malloc-allocated buffer containing a useful error message. The
  653. * caller of this function (the VM) will make sure that the buffer is
  654. * freed.
  655. *
  656. * \param child_isolate_data The callback data to associate with the new
  657. * child isolate.
  658. * \param error A structure into which the embedder can place a
  659. * C string containing an error message in the case the initialization fails.
  660. *
  661. * \return The embedder returns true if the initialization was successful and
  662. * false otherwise (in which case the VM will terminate the isolate).
  663. */
  664. typedef bool (*Dart_InitializeIsolateCallback)(void** child_isolate_data,
  665. char** error);
  666. /**
  667. * An isolate shutdown callback function.
  668. *
  669. * This callback, provided by the embedder, is called before the vm
  670. * shuts down an isolate. The isolate being shutdown will be the current
  671. * isolate. It is safe to run Dart code.
  672. *
  673. * This function should be used to dispose of native resources that
  674. * are allocated to an isolate in order to avoid leaks.
  675. *
  676. * \param isolate_group_data The same callback data which was passed to the
  677. * isolate group when it was created.
  678. * \param isolate_data The same callback data which was passed to the isolate
  679. * when it was created.
  680. */
  681. typedef void (*Dart_IsolateShutdownCallback)(void* isolate_group_data,
  682. void* isolate_data);
  683. /**
  684. * An isolate cleanup callback function.
  685. *
  686. * This callback, provided by the embedder, is called after the vm
  687. * shuts down an isolate. There will be no current isolate and it is *not*
  688. * safe to run Dart code.
  689. *
  690. * This function should be used to dispose of native resources that
  691. * are allocated to an isolate in order to avoid leaks.
  692. *
  693. * \param isolate_group_data The same callback data which was passed to the
  694. * isolate group when it was created.
  695. * \param isolate_data The same callback data which was passed to the isolate
  696. * when it was created.
  697. */
  698. typedef void (*Dart_IsolateCleanupCallback)(void* isolate_group_data,
  699. void* isolate_data);
  700. /**
  701. * An isolate group cleanup callback function.
  702. *
  703. * This callback, provided by the embedder, is called after the vm
  704. * shuts down an isolate group.
  705. *
  706. * This function should be used to dispose of native resources that
  707. * are allocated to an isolate in order to avoid leaks.
  708. *
  709. * \param isolate_group_data The same callback data which was passed to the
  710. * isolate group when it was created.
  711. *
  712. */
  713. typedef void (*Dart_IsolateGroupCleanupCallback)(void* isolate_group_data);
  714. /**
  715. * A thread start callback function.
  716. * This callback, provided by the embedder, is called after a thread in the
  717. * vm thread pool starts.
  718. * This function could be used to adjust thread priority or attach native
  719. * resources to the thread.
  720. */
  721. typedef void (*Dart_ThreadStartCallback)(void);
  722. /**
  723. * A thread death callback function.
  724. * This callback, provided by the embedder, is called before a thread in the
  725. * vm thread pool exits.
  726. * This function could be used to dispose of native resources that
  727. * are associated and attached to the thread, in order to avoid leaks.
  728. */
  729. typedef void (*Dart_ThreadExitCallback)(void);
  730. /**
  731. * Opens a file for reading or writing.
  732. *
  733. * Callback provided by the embedder for file operations. If the
  734. * embedder does not allow file operations this callback can be
  735. * NULL.
  736. *
  737. * \param name The name of the file to open.
  738. * \param write A boolean variable which indicates if the file is to
  739. * opened for writing. If there is an existing file it needs to truncated.
  740. */
  741. typedef void* (*Dart_FileOpenCallback)(const char* name, bool write);
  742. /**
  743. * Read contents of file.
  744. *
  745. * Callback provided by the embedder for file operations. If the
  746. * embedder does not allow file operations this callback can be
  747. * NULL.
  748. *
  749. * \param data Buffer allocated in the callback into which the contents
  750. * of the file are read into. It is the responsibility of the caller to
  751. * free this buffer.
  752. * \param file_length A variable into which the length of the file is returned.
  753. * In the case of an error this value would be -1.
  754. * \param stream Handle to the opened file.
  755. */
  756. typedef void (*Dart_FileReadCallback)(uint8_t** data,
  757. intptr_t* file_length,
  758. void* stream);
  759. /**
  760. * Write data into file.
  761. *
  762. * Callback provided by the embedder for file operations. If the
  763. * embedder does not allow file operations this callback can be
  764. * NULL.
  765. *
  766. * \param data Buffer which needs to be written into the file.
  767. * \param length Length of the buffer.
  768. * \param stream Handle to the opened file.
  769. */
  770. typedef void (*Dart_FileWriteCallback)(const void* data,
  771. intptr_t length,
  772. void* stream);
  773. /**
  774. * Closes the opened file.
  775. *
  776. * Callback provided by the embedder for file operations. If the
  777. * embedder does not allow file operations this callback can be
  778. * NULL.
  779. *
  780. * \param stream Handle to the opened file.
  781. */
  782. typedef void (*Dart_FileCloseCallback)(void* stream);
  783. typedef bool (*Dart_EntropySource)(uint8_t* buffer, intptr_t length);
  784. /**
  785. * Callback provided by the embedder that is used by the vmservice isolate
  786. * to request the asset archive. The asset archive must be an uncompressed tar
  787. * archive that is stored in a Uint8List.
  788. *
  789. * If the embedder has no vmservice isolate assets, the callback can be NULL.
  790. *
  791. * \return The embedder must return a handle to a Uint8List containing an
  792. * uncompressed tar archive or null.
  793. */
  794. typedef Dart_Handle (*Dart_GetVMServiceAssetsArchive)(void);
  795. /**
  796. * The current version of the Dart_InitializeFlags. Should be incremented every
  797. * time Dart_InitializeFlags changes in a binary incompatible way.
  798. */
  799. #define DART_INITIALIZE_PARAMS_CURRENT_VERSION (0x00000008)
  800. /** Forward declaration */
  801. struct Dart_CodeObserver;
  802. /**
  803. * Callback provided by the embedder that is used by the VM to notify on code
  804. * object creation, *before* it is invoked the first time.
  805. * This is useful for embedders wanting to e.g. keep track of PCs beyond
  806. * the lifetime of the garbage collected code objects.
  807. * Note that an address range may be used by more than one code object over the
  808. * lifecycle of a process. Clients of this function should record timestamps for
  809. * these compilation events and when collecting PCs to disambiguate reused
  810. * address ranges.
  811. */
  812. typedef void (*Dart_OnNewCodeCallback)(struct Dart_CodeObserver* observer,
  813. const char* name,
  814. uintptr_t base,
  815. uintptr_t size);
  816. typedef struct Dart_CodeObserver {
  817. void* data;
  818. Dart_OnNewCodeCallback on_new_code;
  819. } Dart_CodeObserver;
  820. /**
  821. * Optional callback provided by the embedder that is used by the VM to
  822. * implement registration of kernel blobs for the subsequent Isolate.spawnUri
  823. * If no callback is provided, the registration of kernel blobs will throw
  824. * an error.
  825. *
  826. * \param kernel_buffer A buffer which contains a kernel program. Callback
  827. * should copy the contents of `kernel_buffer` as
  828. * it may be freed immediately after registration.
  829. * \param kernel_buffer_size The size of `kernel_buffer`.
  830. *
  831. * \return A C string representing URI which can be later used
  832. * to spawn a new isolate. This C String should be scope allocated
  833. * or owned by the embedder.
  834. * Returns NULL if embedder runs out of memory.
  835. */
  836. typedef const char* (*Dart_RegisterKernelBlobCallback)(
  837. const uint8_t* kernel_buffer,
  838. intptr_t kernel_buffer_size);
  839. /**
  840. * Optional callback provided by the embedder that is used by the VM to
  841. * unregister kernel blobs.
  842. * If no callback is provided, the unregistration of kernel blobs will throw
  843. * an error.
  844. *
  845. * \param kernel_blob_uri URI of the kernel blob to unregister.
  846. */
  847. typedef void (*Dart_UnregisterKernelBlobCallback)(const char* kernel_blob_uri);
  848. /**
  849. * Describes how to initialize the VM. Used with Dart_Initialize.
  850. */
  851. typedef struct {
  852. /**
  853. * Identifies the version of the struct used by the client.
  854. * should be initialized to DART_INITIALIZE_PARAMS_CURRENT_VERSION.
  855. */
  856. int32_t version;
  857. /**
  858. * A buffer containing snapshot data, or NULL if no snapshot is provided.
  859. *
  860. * If provided, the buffer must remain valid until Dart_Cleanup returns.
  861. */
  862. const uint8_t* vm_snapshot_data;
  863. /**
  864. * A buffer containing a snapshot of precompiled instructions, or NULL if
  865. * no snapshot is provided.
  866. *
  867. * If provided, the buffer must remain valid until Dart_Cleanup returns.
  868. */
  869. const uint8_t* vm_snapshot_instructions;
  870. /**
  871. * A function to be called during isolate group creation.
  872. * See Dart_IsolateGroupCreateCallback.
  873. */
  874. Dart_IsolateGroupCreateCallback create_group;
  875. /**
  876. * A function to be called during isolate
  877. * initialization inside an existing isolate group.
  878. * See Dart_InitializeIsolateCallback.
  879. */
  880. Dart_InitializeIsolateCallback initialize_isolate;
  881. /**
  882. * A function to be called right before an isolate is shutdown.
  883. * See Dart_IsolateShutdownCallback.
  884. */
  885. Dart_IsolateShutdownCallback shutdown_isolate;
  886. /**
  887. * A function to be called after an isolate was shutdown.
  888. * See Dart_IsolateCleanupCallback.
  889. */
  890. Dart_IsolateCleanupCallback cleanup_isolate;
  891. /**
  892. * A function to be called after an isolate group is
  893. * shutdown. See Dart_IsolateGroupCleanupCallback.
  894. */
  895. Dart_IsolateGroupCleanupCallback cleanup_group;
  896. Dart_ThreadStartCallback thread_start;
  897. Dart_ThreadExitCallback thread_exit;
  898. Dart_FileOpenCallback file_open;
  899. Dart_FileReadCallback file_read;
  900. Dart_FileWriteCallback file_write;
  901. Dart_FileCloseCallback file_close;
  902. Dart_EntropySource entropy_source;
  903. /**
  904. * A function to be called by the service isolate when it requires the
  905. * vmservice assets archive. See Dart_GetVMServiceAssetsArchive.
  906. */
  907. Dart_GetVMServiceAssetsArchive get_service_assets;
  908. bool start_kernel_isolate;
  909. /**
  910. * An external code observer callback function. The observer can be invoked
  911. * as early as during the Dart_Initialize() call.
  912. */
  913. Dart_CodeObserver* code_observer;
  914. /**
  915. * Kernel blob registration callback function. See Dart_RegisterKernelBlobCallback.
  916. */
  917. Dart_RegisterKernelBlobCallback register_kernel_blob;
  918. /**
  919. * Kernel blob unregistration callback function. See Dart_UnregisterKernelBlobCallback.
  920. */
  921. Dart_UnregisterKernelBlobCallback unregister_kernel_blob;
  922. #if defined(__Fuchsia__)
  923. /**
  924. * The resource needed to use zx_vmo_replace_as_executable. Can be
  925. * ZX_HANDLE_INVALID if the process has ambient-replace-as-executable or if
  926. * executable memory is not needed (e.g., this is an AOT runtime).
  927. */
  928. zx_handle_t vmex_resource;
  929. #endif
  930. } Dart_InitializeParams;
  931. /**
  932. * Initializes the VM.
  933. *
  934. * \param params A struct containing initialization information. The version
  935. * field of the struct must be DART_INITIALIZE_PARAMS_CURRENT_VERSION.
  936. *
  937. * \return NULL if initialization is successful. Returns an error message
  938. * otherwise. The caller is responsible for freeing the error message.
  939. */
  940. DART_EXPORT DART_WARN_UNUSED_RESULT char* Dart_Initialize(
  941. Dart_InitializeParams* params);
  942. /**
  943. * Cleanup state in the VM before process termination.
  944. *
  945. * \return NULL if cleanup is successful. Returns an error message otherwise.
  946. * The caller is responsible for freeing the error message.
  947. *
  948. * NOTE: This function must not be called on a thread that was created by the VM
  949. * itself.
  950. */
  951. DART_EXPORT DART_WARN_UNUSED_RESULT char* Dart_Cleanup(void);
  952. /**
  953. * Sets command line flags. Should be called before Dart_Initialize.
  954. *
  955. * \param argc The length of the arguments array.
  956. * \param argv An array of arguments.
  957. *
  958. * \return NULL if successful. Returns an error message otherwise.
  959. * The caller is responsible for freeing the error message.
  960. *
  961. * NOTE: This call does not store references to the passed in c-strings.
  962. */
  963. DART_EXPORT DART_WARN_UNUSED_RESULT char* Dart_SetVMFlags(int argc,
  964. const char** argv);
  965. /**
  966. * Returns true if the named VM flag is of boolean type, specified, and set to
  967. * true.
  968. *
  969. * \param flag_name The name of the flag without leading punctuation
  970. * (example: "enable_asserts").
  971. */
  972. DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name);
  973. /*
  974. * ========
  975. * Isolates
  976. * ========
  977. */
  978. /**
  979. * Creates a new isolate. The new isolate becomes the current isolate.
  980. *
  981. * A snapshot can be used to restore the VM quickly to a saved state
  982. * and is useful for fast startup. If snapshot data is provided, the
  983. * isolate will be started using that snapshot data. Requires a core snapshot or
  984. * an app snapshot created by Dart_CreateSnapshot or
  985. * Dart_CreatePrecompiledSnapshot* from a VM with the same version.
  986. *
  987. * Requires there to be no current isolate.
  988. *
  989. * \param script_uri The main source file or snapshot this isolate will load.
  990. * The VM will provide this URI to the Dart_IsolateGroupCreateCallback when a
  991. * child isolate is created by Isolate.spawn. The embedder should use a URI
  992. * that allows it to load the same program into such a child isolate.
  993. * \param name A short name for the isolate to improve debugging messages.
  994. * Typically of the format 'foo.dart:main()'.
  995. * \param isolate_snapshot_data Buffer containing the snapshot data of the
  996. * isolate or NULL if no snapshot is provided. If provided, the buffer must
  997. * remain valid until the isolate shuts down.
  998. * \param isolate_snapshot_instructions Buffer containing the snapshot
  999. * instructions of the isolate or NULL if no snapshot is provided. If
  1000. * provided, the buffer must remain valid until the isolate shuts down.
  1001. * \param flags Pointer to VM specific flags or NULL for default flags.
  1002. * \param isolate_group_data Embedder group data. This data can be obtained
  1003. * by calling Dart_IsolateGroupData and will be passed to the
  1004. * Dart_IsolateShutdownCallback, Dart_IsolateCleanupCallback, and
  1005. * Dart_IsolateGroupCleanupCallback.
  1006. * \param isolate_data Embedder data. This data will be passed to
  1007. * the Dart_IsolateGroupCreateCallback when new isolates are spawned from
  1008. * this parent isolate.
  1009. * \param error Returns NULL if creation is successful, an error message
  1010. * otherwise. The caller is responsible for calling free() on the error
  1011. * message.
  1012. *
  1013. * \return The new isolate on success, or NULL if isolate creation failed.
  1014. */
  1015. DART_EXPORT Dart_Isolate
  1016. Dart_CreateIsolateGroup(const char* script_uri,
  1017. const char* name,
  1018. const uint8_t* isolate_snapshot_data,
  1019. const uint8_t* isolate_snapshot_instructions,
  1020. Dart_IsolateFlags* flags,
  1021. void* isolate_group_data,
  1022. void* isolate_data,
  1023. char** error);
  1024. /**
  1025. * Creates a new isolate inside the isolate group of [group_member].
  1026. *
  1027. * Requires there to be no current isolate.
  1028. *
  1029. * \param group_member An isolate from the same group into which the newly created
  1030. * isolate should be born into. Other threads may not have entered / enter this
  1031. * member isolate.
  1032. * \param name A short name for the isolate for debugging purposes.
  1033. * \param shutdown_callback A callback to be called when the isolate is being
  1034. * shutdown (may be NULL).
  1035. * \param cleanup_callback A callback to be called when the isolate is being
  1036. * cleaned up (may be NULL).
  1037. * \param child_isolate_data The embedder-specific data associated with this isolate.
  1038. * \param error Set to NULL if creation is successful, set to an error
  1039. * message otherwise. The caller is responsible for calling free() on the
  1040. * error message.
  1041. *
  1042. * \return The newly created isolate on success, or NULL if isolate creation
  1043. * failed.
  1044. *
  1045. * If successful, the newly created isolate will become the current isolate.
  1046. */
  1047. DART_EXPORT Dart_Isolate
  1048. Dart_CreateIsolateInGroup(Dart_Isolate group_member,
  1049. const char* name,
  1050. Dart_IsolateShutdownCallback shutdown_callback,
  1051. Dart_IsolateCleanupCallback cleanup_callback,
  1052. void* child_isolate_data,
  1053. char** error);
  1054. /* TODO(turnidge): Document behavior when there is already a current
  1055. * isolate. */
  1056. /**
  1057. * Creates a new isolate from a Dart Kernel file. The new isolate
  1058. * becomes the current isolate.
  1059. *
  1060. * Requires there to be no current isolate.
  1061. *
  1062. * \param script_uri The main source file or snapshot this isolate will load.
  1063. * The VM will provide this URI to the Dart_IsolateGroupCreateCallback when a
  1064. * child isolate is created by Isolate.spawn. The embedder should use a URI that
  1065. * allows it to load the same program into such a child isolate.
  1066. * \param name A short name for the isolate to improve debugging messages.
  1067. * Typically of the format 'foo.dart:main()'.
  1068. * \param kernel_buffer A buffer which contains a kernel/DIL program. Must
  1069. * remain valid until isolate shutdown.
  1070. * \param kernel_buffer_size The size of `kernel_buffer`.
  1071. * \param flags Pointer to VM specific flags or NULL for default flags.
  1072. * \param isolate_group_data Embedder group data. This data can be obtained
  1073. * by calling Dart_IsolateGroupData and will be passed to the
  1074. * Dart_IsolateShutdownCallback, Dart_IsolateCleanupCallback, and
  1075. * Dart_IsolateGroupCleanupCallback.
  1076. * \param isolate_data Embedder data. This data will be passed to
  1077. * the Dart_IsolateGroupCreateCallback when new isolates are spawned from
  1078. * this parent isolate.
  1079. * \param error Returns NULL if creation is successful, an error message
  1080. * otherwise. The caller is responsible for calling free() on the error
  1081. * message.
  1082. *
  1083. * \return The new isolate on success, or NULL if isolate creation failed.
  1084. */
  1085. DART_EXPORT Dart_Isolate
  1086. Dart_CreateIsolateGroupFromKernel(const char* script_uri,
  1087. const char* name,
  1088. const uint8_t* kernel_buffer,
  1089. intptr_t kernel_buffer_size,
  1090. Dart_IsolateFlags* flags,
  1091. void* isolate_group_data,
  1092. void* isolate_data,
  1093. char** error);
  1094. /**
  1095. * Shuts down the current isolate. After this call, the current isolate is NULL.
  1096. * Any current scopes created by Dart_EnterScope will be exited. Invokes the
  1097. * shutdown callback and any callbacks of remaining weak persistent handles.
  1098. *
  1099. * Requires there to be a current isolate.
  1100. */
  1101. DART_EXPORT void Dart_ShutdownIsolate(void);
  1102. /* TODO(turnidge): Document behavior when there is no current isolate. */
  1103. /**
  1104. * Returns the current isolate. Will return NULL if there is no
  1105. * current isolate.
  1106. */
  1107. DART_EXPORT Dart_Isolate Dart_CurrentIsolate(void);
  1108. /**
  1109. * Returns the callback data associated with the current isolate. This
  1110. * data was set when the isolate got created or initialized.
  1111. */
  1112. DART_EXPORT void* Dart_CurrentIsolateData(void);
  1113. /**
  1114. * Returns the callback data associated with the given isolate. This
  1115. * data was set when the isolate got created or initialized.
  1116. */
  1117. DART_EXPORT void* Dart_IsolateData(Dart_Isolate isolate);
  1118. /**
  1119. * Returns the current isolate group. Will return NULL if there is no
  1120. * current isolate group.
  1121. */
  1122. DART_EXPORT Dart_IsolateGroup Dart_CurrentIsolateGroup(void);
  1123. /**
  1124. * Returns the callback data associated with the current isolate group. This
  1125. * data was passed to the isolate group when it was created.
  1126. */
  1127. DART_EXPORT void* Dart_CurrentIsolateGroupData(void);
  1128. /**
  1129. * Gets an id that uniquely identifies current isolate group.
  1130. *
  1131. * It is the responsibility of the caller to free the returned ID.
  1132. */
  1133. typedef int64_t Dart_IsolateGroupId;
  1134. DART_EXPORT Dart_IsolateGroupId Dart_CurrentIsolateGroupId(void);
  1135. /**
  1136. * Returns the callback data associated with the specified isolate group. This
  1137. * data was passed to the isolate when it was created.
  1138. * The embedder is responsible for ensuring the consistency of this data
  1139. * with respect to the lifecycle of an isolate group.
  1140. */
  1141. DART_EXPORT void* Dart_IsolateGroupData(Dart_Isolate isolate);
  1142. /**
  1143. * Returns the debugging name for the current isolate.
  1144. *
  1145. * This name is unique to each isolate and should only be used to make
  1146. * debugging messages more comprehensible.
  1147. */
  1148. DART_EXPORT Dart_Handle Dart_DebugName(void);
  1149. /**
  1150. * Returns the debugging name for the current isolate.
  1151. *
  1152. * This name is unique to each isolate and should only be used to make
  1153. * debugging messages more comprehensible.
  1154. *
  1155. * The returned string is scope allocated and is only valid until the next call
  1156. * to Dart_ExitScope.
  1157. */
  1158. DART_EXPORT const char* Dart_DebugNameToCString(void);
  1159. /**
  1160. * Returns the ID for an isolate which is used to query the service protocol.
  1161. *
  1162. * It is the responsibility of the caller to free the returned ID.
  1163. */
  1164. DART_EXPORT const char* Dart_IsolateServiceId(Dart_Isolate isolate);
  1165. /**
  1166. * Enters an isolate. After calling this function,
  1167. * the current isolate will be set to the provided isolate.
  1168. *
  1169. * Requires there to be no current isolate. Multiple threads may not be in
  1170. * the same isolate at once.
  1171. */
  1172. DART_EXPORT void Dart_EnterIsolate(Dart_Isolate isolate);
  1173. /**
  1174. * Kills the given isolate.
  1175. *
  1176. * This function has the same effect as dart:isolate's
  1177. * Isolate.kill(priority:immediate).
  1178. * It can interrupt ordinary Dart code but not native code. If the isolate is
  1179. * in the middle of a long running native function, the isolate will not be
  1180. * killed until control returns to Dart.
  1181. *
  1182. * Does not require a current isolate. It is safe to kill the current isolate if
  1183. * there is one.
  1184. */
  1185. DART_EXPORT void Dart_KillIsolate(Dart_Isolate isolate);
  1186. /**
  1187. * Notifies the VM that the embedder expects to be idle until |deadline|. The VM
  1188. * may use this time to perform garbage collection or other tasks to avoid
  1189. * delays during execution of Dart code in the future.
  1190. *
  1191. * |deadline| is measured in microseconds against the system's monotonic time.
  1192. * This clock can be accessed via Dart_TimelineGetMicros().
  1193. *
  1194. * Requires there to be a current isolate.
  1195. */
  1196. DART_EXPORT void Dart_NotifyIdle(int64_t deadline);
  1197. typedef void (*Dart_HeapSamplingReportCallback)(void* context,
  1198. void* data);
  1199. typedef void* (*Dart_HeapSamplingCreateCallback)(
  1200. Dart_Isolate isolate,
  1201. Dart_IsolateGroup isolate_group,
  1202. const char* cls_name,
  1203. intptr_t allocation_size);
  1204. typedef void (*Dart_HeapSamplingDeleteCallback)(void* data);
  1205. /**
  1206. * Starts the heap sampling profiler for each thread in the VM.
  1207. */
  1208. DART_EXPORT void Dart_EnableHeapSampling(void);
  1209. /*
  1210. * Stops the heap sampling profiler for each thread in the VM.
  1211. */
  1212. DART_EXPORT void Dart_DisableHeapSampling(void);
  1213. /* Registers callbacks are invoked once per sampled allocation upon object
  1214. * allocation and garbage collection.
  1215. *
  1216. * |create_callback| can be used to associate additional data with the sampled
  1217. * allocation, such as a stack trace. This data pointer will be passed to
  1218. * |delete_callback| to allow for proper disposal when the object associated
  1219. * with the allocation sample is collected.
  1220. *
  1221. * The provided callbacks must not call into the VM and should do as little
  1222. * work as possible to avoid performance penalities during object allocation and
  1223. * garbage collection.
  1224. *
  1225. * NOTE: It is a fatal error to set either callback to null once they have been
  1226. * initialized.
  1227. */
  1228. DART_EXPORT void Dart_RegisterHeapSamplingCallback(
  1229. Dart_HeapSamplingCreateCallback create_callback,
  1230. Dart_HeapSamplingDeleteCallback delete_callback);
  1231. /*
  1232. * Reports the surviving allocation samples for all live isolate groups in the
  1233. * VM.
  1234. *
  1235. * When the callback is invoked:
  1236. * - |context| will be the context object provided when invoking
  1237. * |Dart_ReportSurvivingAllocations|. This can be safely set to null if not
  1238. * required.
  1239. * - |heap_size| will be equal to the size of the allocated object associated
  1240. * with the sample.
  1241. * - |cls_name| will be a C String representing
  1242. * the class name of the allocated object. This string is valid for the
  1243. * duration of the call to Dart_ReportSurvivingAllocations and can be
  1244. * freed by the VM at any point after the method returns.
  1245. * - |data| will be set to the data associated with the sample by
  1246. * |Dart_HeapSamplingCreateCallback|.
  1247. *
  1248. * If |force_gc| is true, a full GC will be performed before reporting the
  1249. * allocations.
  1250. */
  1251. DART_EXPORT void Dart_ReportSurvivingAllocations(
  1252. Dart_HeapSamplingReportCallback callback,
  1253. void* context,
  1254. bool force_gc);
  1255. /*
  1256. * Sets the average heap sampling rate based on a number of |bytes| for each
  1257. * thread.
  1258. *
  1259. * In other words, approximately every |bytes| allocated will create a sample.
  1260. * Defaults to 512 KiB.
  1261. */
  1262. DART_EXPORT void Dart_SetHeapSamplingPeriod(intptr_t bytes);
  1263. /**
  1264. * Notifies the VM that the embedder expects the application's working set has
  1265. * recently shrunk significantly and is not expected to rise in the near future.
  1266. * The VM may spend O(heap-size) time performing clean up work.
  1267. *
  1268. * Requires there to be a current isolate.
  1269. */
  1270. DART_EXPORT void Dart_NotifyDestroyed(void);
  1271. /**
  1272. * Notifies the VM that the system is running low on memory.
  1273. *
  1274. * Does not require a current isolate. Only valid after calling Dart_Initialize.
  1275. */
  1276. DART_EXPORT void Dart_NotifyLowMemory(void);
  1277. typedef enum {
  1278. /**
  1279. * Balanced
  1280. */
  1281. Dart_PerformanceMode_Default,
  1282. /**
  1283. * Optimize for low latency, at the expense of throughput and memory overhead
  1284. * by performing work in smaller batches (requiring more overhead) or by
  1285. * delaying work (requiring more memory). An embedder should not remain in
  1286. * this mode indefinitely.
  1287. */
  1288. Dart_PerformanceMode_Latency,
  1289. /**
  1290. * Optimize for high throughput, at the expense of latency and memory overhead
  1291. * by performing work in larger batches with more intervening growth.
  1292. */
  1293. Dart_PerformanceMode_Throughput,
  1294. /**
  1295. * Optimize for low memory, at the expensive of throughput and latency by more
  1296. * frequently performing work.
  1297. */
  1298. Dart_PerformanceMode_Memory,
  1299. } Dart_PerformanceMode;
  1300. /**
  1301. * Set the desired performance trade-off.
  1302. *
  1303. * Requires a current isolate.
  1304. *
  1305. * Returns the previous performance mode.
  1306. */
  1307. DART_EXPORT Dart_PerformanceMode
  1308. Dart_SetPerformanceMode(Dart_PerformanceMode mode);
  1309. /**
  1310. * Starts the CPU sampling profiler.
  1311. */
  1312. DART_EXPORT void Dart_StartProfiling(void);
  1313. /**
  1314. * Stops the CPU sampling profiler.
  1315. *
  1316. * Note that some profile samples might still be taken after this function
  1317. * returns due to the asynchronous nature of the implementation on some
  1318. * platforms.
  1319. */
  1320. DART_EXPORT void Dart_StopProfiling(void);
  1321. /**
  1322. * Notifies the VM that the current thread should not be profiled until a
  1323. * matching call to Dart_ThreadEnableProfiling is made.
  1324. *
  1325. * NOTE: By default, if a thread has entered an isolate it will be profiled.
  1326. * This function should be used when an embedder knows a thread is about
  1327. * to make a blocking call and wants to avoid unnecessary interrupts by
  1328. * the profiler.
  1329. */
  1330. DART_EXPORT void Dart_ThreadDisableProfiling(void);
  1331. /**
  1332. * Notifies the VM that the current thread should be profiled.
  1333. *
  1334. * NOTE: It is only legal to call this function *after* calling
  1335. * Dart_ThreadDisableProfiling.
  1336. *
  1337. * NOTE: By default, if a thread has entered an isolate it will be profiled.
  1338. */
  1339. DART_EXPORT void Dart_ThreadEnableProfiling(void);
  1340. /**
  1341. * Register symbol information for the Dart VM's profiler and crash dumps.
  1342. *
  1343. * This consumes the output of //topaz/runtime/dart/profiler_symbols, which
  1344. * should be treated as opaque.
  1345. */
  1346. DART_EXPORT void Dart_AddSymbols(const char* dso_name,
  1347. void* buffer,
  1348. intptr_t buffer_size);
  1349. /**
  1350. * Exits an isolate. After this call, Dart_CurrentIsolate will
  1351. * return NULL.
  1352. *
  1353. * Requires there to be a current isolate.
  1354. */
  1355. DART_EXPORT void Dart_ExitIsolate(void);
  1356. /* TODO(turnidge): We don't want users of the api to be able to exit a
  1357. * "pure" dart isolate. Implement and document. */
  1358. /**
  1359. * Creates a full snapshot of the current isolate heap.
  1360. *
  1361. * A full snapshot is a compact representation of the dart vm isolate heap
  1362. * and dart isolate heap states. These snapshots are used to initialize
  1363. * the vm isolate on startup and fast initialization of an isolate.
  1364. * A Snapshot of the heap is created before any dart code has executed.
  1365. *
  1366. * Requires there to be a current isolate. Not available in the precompiled
  1367. * runtime (check Dart_IsPrecompiledRuntime).
  1368. *
  1369. * \param vm_snapshot_data_buffer Returns a pointer to a buffer containing the
  1370. * vm snapshot. This buffer is scope allocated and is only valid
  1371. * until the next call to Dart_ExitScope.
  1372. * \param vm_snapshot_data_size Returns the size of vm_snapshot_data_buffer.
  1373. * \param isolate_snapshot_data_buffer Returns a pointer to a buffer containing
  1374. * the isolate snapshot. This buffer is scope allocated and is only valid
  1375. * until the next call to Dart_ExitScope.
  1376. * \param isolate_snapshot_data_size Returns the size of
  1377. * isolate_snapshot_data_buffer.
  1378. * \param is_core Create a snapshot containing core libraries.
  1379. * Such snapshot should be agnostic to null safety mode.
  1380. *
  1381. * \return A valid handle if no error occurs during the operation.
  1382. */
  1383. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  1384. Dart_CreateSnapshot(uint8_t** vm_snapshot_data_buffer,
  1385. intptr_t* vm_snapshot_data_size,
  1386. uint8_t** isolate_snapshot_data_buffer,
  1387. intptr_t* isolate_snapshot_data_size,
  1388. bool is_core);
  1389. /**
  1390. * Returns whether the buffer contains a kernel file.
  1391. *
  1392. * \param buffer Pointer to a buffer that might contain a kernel binary.
  1393. * \param buffer_size Size of the buffer.
  1394. *
  1395. * \return Whether the buffer contains a kernel binary (full or partial).
  1396. */
  1397. DART_EXPORT bool Dart_IsKernel(const uint8_t* buffer, intptr_t buffer_size);
  1398. /**
  1399. * Make isolate runnable.
  1400. *
  1401. * When isolates are spawned, this function is used to indicate that
  1402. * the creation and initialization (including script loading) of the
  1403. * isolate is complete and the isolate can start.
  1404. * This function expects there to be no current isolate.
  1405. *
  1406. * \param isolate The isolate to be made runnable.
  1407. *
  1408. * \return NULL if successful. Returns an error message otherwise. The caller
  1409. * is responsible for freeing the error message.
  1410. */
  1411. DART_EXPORT DART_WARN_UNUSED_RESULT char* Dart_IsolateMakeRunnable(
  1412. Dart_Isolate isolate);
  1413. /*
  1414. * ==================
  1415. * Messages and Ports
  1416. * ==================
  1417. */
  1418. /**
  1419. * A port is used to send or receive inter-isolate messages
  1420. */
  1421. typedef int64_t Dart_Port;
  1422. /**
  1423. * ILLEGAL_PORT is a port number guaranteed never to be associated with a valid
  1424. * port.
  1425. */
  1426. #define ILLEGAL_PORT ((Dart_Port)0)
  1427. /**
  1428. * A message notification callback.
  1429. *
  1430. * This callback allows the embedder to provide a custom wakeup mechanism for
  1431. * the delivery of inter-isolate messages. This function is called once per
  1432. * message on an arbitrary thread. It is the responsibility of the embedder to
  1433. * eventually call Dart_HandleMessage once per callback received with the
  1434. * destination isolate set as the current isolate to process the message.
  1435. */
  1436. typedef void (*Dart_MessageNotifyCallback)(Dart_Isolate destination_isolate);
  1437. /**
  1438. * Allows embedders to provide a custom wakeup mechanism for the delivery of
  1439. * inter-isolate messages. This setting only applies to the current isolate.
  1440. *
  1441. * This mechanism is optional: if not provided, the isolate will be scheduled on
  1442. * a VM-managed thread pool. An embedder should provide this callback if it
  1443. * wants to run an isolate on a specific thread or to interleave handling of
  1444. * inter-isolate messages with other event sources.
  1445. *
  1446. * Most embedders will only call this function once, before isolate
  1447. * execution begins. If this function is called after isolate
  1448. * execution begins, the embedder is responsible for threading issues.
  1449. */
  1450. DART_EXPORT void Dart_SetMessageNotifyCallback(
  1451. Dart_MessageNotifyCallback message_notify_callback);
  1452. /* TODO(turnidge): Consider moving this to isolate creation so that it
  1453. * is impossible to mess up. */
  1454. /**
  1455. * Query the current message notify callback for the isolate.
  1456. *
  1457. * \return The current message notify callback for the isolate.
  1458. */
  1459. DART_EXPORT Dart_MessageNotifyCallback Dart_GetMessageNotifyCallback(void);
  1460. /**
  1461. * The VM's default message handler supports pausing an isolate before it
  1462. * processes the first message and right after the it processes the isolate's
  1463. * final message. This can be controlled for all isolates by two VM flags:
  1464. *
  1465. * `--pause-isolates-on-start`
  1466. * `--pause-isolates-on-exit`
  1467. *
  1468. * Additionally, Dart_SetShouldPauseOnStart and Dart_SetShouldPauseOnExit can be
  1469. * used to control this behaviour on a per-isolate basis.
  1470. *
  1471. * When an embedder is using a Dart_MessageNotifyCallback the embedder
  1472. * needs to cooperate with the VM so that the service protocol can report
  1473. * accurate information about isolates and so that tools such as debuggers
  1474. * work reliably.
  1475. *
  1476. * The following functions can be used to implement pausing on start and exit.
  1477. */
  1478. /**
  1479. * If the VM flag `--pause-isolates-on-start` was passed this will be true.
  1480. *
  1481. * \return A boolean value indicating if pause on start was requested.
  1482. */
  1483. DART_EXPORT bool Dart_ShouldPauseOnStart(void);
  1484. /**
  1485. * Override the VM flag `--pause-isolates-on-start` for the current isolate.
  1486. *
  1487. * \param should_pause Should the isolate be paused on start?
  1488. *
  1489. * NOTE: This must be called before Dart_IsolateMakeRunnable.
  1490. */
  1491. DART_EXPORT void Dart_SetShouldPauseOnStart(bool should_pause);
  1492. /**
  1493. * Is the current isolate paused on start?
  1494. *
  1495. * \return A boolean value indicating if the isolate is paused on start.
  1496. */
  1497. DART_EXPORT bool Dart_IsPausedOnStart(void);
  1498. /**
  1499. * Called when the embedder has paused the current isolate on start and when
  1500. * the embedder has resumed the isolate.
  1501. *
  1502. * \param paused Is the isolate paused on start?
  1503. */
  1504. DART_EXPORT void Dart_SetPausedOnStart(bool paused);
  1505. /**
  1506. * If the VM flag `--pause-isolates-on-exit` was passed this will be true.
  1507. *
  1508. * \return A boolean value indicating if pause on exit was requested.
  1509. */
  1510. DART_EXPORT bool Dart_ShouldPauseOnExit(void);
  1511. /**
  1512. * Override the VM flag `--pause-isolates-on-exit` for the current isolate.
  1513. *
  1514. * \param should_pause Should the isolate be paused on exit?
  1515. *
  1516. */
  1517. DART_EXPORT void Dart_SetShouldPauseOnExit(bool should_pause);
  1518. /**
  1519. * Is the current isolate paused on exit?
  1520. *
  1521. * \return A boolean value indicating if the isolate is paused on exit.
  1522. */
  1523. DART_EXPORT bool Dart_IsPausedOnExit(void);
  1524. /**
  1525. * Called when the embedder has paused the current isolate on exit and when
  1526. * the embedder has resumed the isolate.
  1527. *
  1528. * \param paused Is the isolate paused on exit?
  1529. */
  1530. DART_EXPORT void Dart_SetPausedOnExit(bool paused);
  1531. /**
  1532. * Called when the embedder has caught a top level unhandled exception error
  1533. * in the current isolate.
  1534. *
  1535. * NOTE: It is illegal to call this twice on the same isolate without first
  1536. * clearing the sticky error to null.
  1537. *
  1538. * \param error The unhandled exception error.
  1539. */
  1540. DART_EXPORT void Dart_SetStickyError(Dart_Handle error);
  1541. /**
  1542. * Does the current isolate have a sticky error?
  1543. */
  1544. DART_EXPORT bool Dart_HasStickyError(void);
  1545. /**
  1546. * Gets the sticky error for the current isolate.
  1547. *
  1548. * \return A handle to the sticky error object or null.
  1549. */
  1550. DART_EXPORT Dart_Handle Dart_GetStickyError(void);
  1551. /**
  1552. * Handles the next pending message for the current isolate.
  1553. *
  1554. * May generate an unhandled exception error.
  1555. *
  1556. * \return A valid handle if no error occurs during the operation.
  1557. */
  1558. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_HandleMessage(void);
  1559. /**
  1560. * Drains the microtask queue, then blocks the calling thread until the current
  1561. * isolate receives a message, then handles all messages.
  1562. *
  1563. * \param timeout_millis When non-zero, the call returns after the indicated
  1564. number of milliseconds even if no message was received.
  1565. * \return A valid handle if no error occurs, otherwise an error handle.
  1566. */
  1567. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  1568. Dart_WaitForEvent(int64_t timeout_millis);
  1569. /**
  1570. * Handles any pending messages for the vm service for the current
  1571. * isolate.
  1572. *
  1573. * This function may be used by an embedder at a breakpoint to avoid
  1574. * pausing the vm service.
  1575. *
  1576. * This function can indirectly cause the message notify callback to
  1577. * be called.
  1578. *
  1579. * \return true if the vm service requests the program resume
  1580. * execution, false otherwise
  1581. */
  1582. DART_EXPORT bool Dart_HandleServiceMessages(void);
  1583. /**
  1584. * Does the current isolate have pending service messages?
  1585. *
  1586. * \return true if the isolate has pending service messages, false otherwise.
  1587. */
  1588. DART_EXPORT bool Dart_HasServiceMessages(void);
  1589. /**
  1590. * Processes any incoming messages for the current isolate.
  1591. *
  1592. * This function may only be used when the embedder has not provided
  1593. * an alternate message delivery mechanism with
  1594. * Dart_SetMessageCallbacks. It is provided for convenience.
  1595. *
  1596. * This function waits for incoming messages for the current
  1597. * isolate. As new messages arrive, they are handled using
  1598. * Dart_HandleMessage. The routine exits when all ports to the
  1599. * current isolate are closed.
  1600. *
  1601. * \return A valid handle if the run loop exited successfully. If an
  1602. * exception or other error occurs while processing messages, an
  1603. * error handle is returned.
  1604. */
  1605. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_RunLoop(void);
  1606. /**
  1607. * Lets the VM run message processing for the isolate.
  1608. *
  1609. * This function expects there to a current isolate and the current isolate
  1610. * must not have an active api scope. The VM will take care of making the
  1611. * isolate runnable (if not already), handles its message loop and will take
  1612. * care of shutting the isolate down once it's done.
  1613. *
  1614. * \param errors_are_fatal Whether uncaught errors should be fatal.
  1615. * \param on_error_port A port to notify on uncaught errors (or ILLEGAL_PORT).
  1616. * \param on_exit_port A port to notify on exit (or ILLEGAL_PORT).
  1617. * \param error A non-NULL pointer which will hold an error message if the call
  1618. * fails. The error has to be free()ed by the caller.
  1619. *
  1620. * \return If successful the VM takes ownership of the isolate and takes care
  1621. * of its message loop. If not successful the caller retains ownership of the
  1622. * isolate.
  1623. */
  1624. DART_EXPORT DART_WARN_UNUSED_RESULT bool Dart_RunLoopAsync(
  1625. bool errors_are_fatal,
  1626. Dart_Port on_error_port,
  1627. Dart_Port on_exit_port,
  1628. char** error);
  1629. /* TODO(turnidge): Should this be removed from the public api? */
  1630. /**
  1631. * Gets the main port id for the current isolate.
  1632. */
  1633. DART_EXPORT Dart_Port Dart_GetMainPortId(void);
  1634. /**
  1635. * Does the current isolate have live ReceivePorts?
  1636. *
  1637. * A ReceivePort is live when it has not been closed.
  1638. */
  1639. DART_EXPORT bool Dart_HasLivePorts(void);
  1640. /**
  1641. * Posts a message for some isolate. The message is a serialized
  1642. * object.
  1643. *
  1644. * Requires there to be a current isolate.
  1645. *
  1646. * For posting messages outside of an isolate see \ref Dart_PostCObject.
  1647. *
  1648. * \param port_id The destination port.
  1649. * \param object An object from the current isolate.
  1650. *
  1651. * \return True if the message was posted.
  1652. */
  1653. DART_EXPORT bool Dart_Post(Dart_Port port_id, Dart_Handle object);
  1654. /**
  1655. * Returns a new SendPort with the provided port id.
  1656. *
  1657. * \param port_id The destination port.
  1658. *
  1659. * \return A new SendPort if no errors occurs. Otherwise returns
  1660. * an error handle.
  1661. */
  1662. DART_EXPORT Dart_Handle Dart_NewSendPort(Dart_Port port_id);
  1663. /**
  1664. * Gets the SendPort id for the provided SendPort.
  1665. * \param port A SendPort object whose id is desired.
  1666. * \param port_id Returns the id of the SendPort.
  1667. * \return Success if no error occurs. Otherwise returns
  1668. * an error handle.
  1669. */
  1670. DART_EXPORT Dart_Handle Dart_SendPortGetId(Dart_Handle port,
  1671. Dart_Port* port_id);
  1672. /*
  1673. * ======
  1674. * Scopes
  1675. * ======
  1676. */
  1677. /**
  1678. * Enters a new scope.
  1679. *
  1680. * All new local handles will be created in this scope. Additionally,
  1681. * some functions may return "scope allocated" memory which is only
  1682. * valid within this scope.
  1683. *
  1684. * Requires there to be a current isolate.
  1685. */
  1686. DART_EXPORT void Dart_EnterScope(void);
  1687. /**
  1688. * Exits a scope.
  1689. *
  1690. * The previous scope (if any) becomes the current scope.
  1691. *
  1692. * Requires there to be a current isolate.
  1693. */
  1694. DART_EXPORT void Dart_ExitScope(void);
  1695. /**
  1696. * The Dart VM uses "zone allocation" for temporary structures. Zones
  1697. * support very fast allocation of small chunks of memory. The chunks
  1698. * cannot be deallocated individually, but instead zones support
  1699. * deallocating all chunks in one fast operation.
  1700. *
  1701. * This function makes it possible for the embedder to allocate
  1702. * temporary data in the VMs zone allocator.
  1703. *
  1704. * Zone allocation is possible:
  1705. * 1. when inside a scope where local handles can be allocated
  1706. * 2. when processing a message from a native port in a native port
  1707. * handler
  1708. *
  1709. * All the memory allocated this way will be reclaimed either on the
  1710. * next call to Dart_ExitScope or when the native port handler exits.
  1711. *
  1712. * \param size Size of the memory to allocate.
  1713. *
  1714. * \return A pointer to the allocated memory. NULL if allocation
  1715. * failed. Failure might due to is no current VM zone.
  1716. */
  1717. DART_EXPORT uint8_t* Dart_ScopeAllocate(intptr_t size);
  1718. /*
  1719. * =======
  1720. * Objects
  1721. * =======
  1722. */
  1723. /**
  1724. * Returns the null object.
  1725. *
  1726. * \return A handle to the null object.
  1727. */
  1728. DART_EXPORT Dart_Handle Dart_Null(void);
  1729. /**
  1730. * Is this object null?
  1731. */
  1732. DART_EXPORT bool Dart_IsNull(Dart_Handle object);
  1733. /**
  1734. * Returns the empty string object.
  1735. *
  1736. * \return A handle to the empty string object.
  1737. */
  1738. DART_EXPORT Dart_Handle Dart_EmptyString(void);
  1739. /**
  1740. * Returns types that are not classes, and which therefore cannot be looked up
  1741. * as library members by Dart_GetType.
  1742. *
  1743. * \return A handle to the dynamic, void or Never type.
  1744. */
  1745. DART_EXPORT Dart_Handle Dart_TypeDynamic(void);
  1746. DART_EXPORT Dart_Handle Dart_TypeVoid(void);
  1747. DART_EXPORT Dart_Handle Dart_TypeNever(void);
  1748. /**
  1749. * Checks if the two objects are equal.
  1750. *
  1751. * The result of the comparison is returned through the 'equal'
  1752. * parameter. The return value itself is used to indicate success or
  1753. * failure, not equality.
  1754. *
  1755. * May generate an unhandled exception error.
  1756. *
  1757. * \param obj1 An object to be compared.
  1758. * \param obj2 An object to be compared.
  1759. * \param equal Returns the result of the equality comparison.
  1760. *
  1761. * \return A valid handle if no error occurs during the comparison.
  1762. */
  1763. DART_EXPORT Dart_Handle Dart_ObjectEquals(Dart_Handle obj1,
  1764. Dart_Handle obj2,
  1765. bool* equal);
  1766. /**
  1767. * Is this object an instance of some type?
  1768. *
  1769. * The result of the test is returned through the 'instanceof' parameter.
  1770. * The return value itself is used to indicate success or failure.
  1771. *
  1772. * \param object An object.
  1773. * \param type A type.
  1774. * \param instanceof Return true if 'object' is an instance of type 'type'.
  1775. *
  1776. * \return A valid handle if no error occurs during the operation.
  1777. */
  1778. DART_EXPORT Dart_Handle Dart_ObjectIsType(Dart_Handle object,
  1779. Dart_Handle type,
  1780. bool* instanceof);
  1781. /**
  1782. * Query object type.
  1783. *
  1784. * \param object Some Object.
  1785. *
  1786. * \return true if Object is of the specified type.
  1787. */
  1788. DART_EXPORT bool Dart_IsInstance(Dart_Handle object);
  1789. DART_EXPORT bool Dart_IsNumber(Dart_Handle object);
  1790. DART_EXPORT bool Dart_IsInteger(Dart_Handle object);
  1791. DART_EXPORT bool Dart_IsDouble(Dart_Handle object);
  1792. DART_EXPORT bool Dart_IsBoolean(Dart_Handle object);
  1793. DART_EXPORT bool Dart_IsString(Dart_Handle object);
  1794. DART_EXPORT bool Dart_IsStringLatin1(Dart_Handle object); /* (ISO-8859-1) */
  1795. DART_EXPORT bool Dart_IsExternalString(Dart_Handle object);
  1796. DART_EXPORT bool Dart_IsList(Dart_Handle object);
  1797. DART_EXPORT bool Dart_IsMap(Dart_Handle object);
  1798. DART_EXPORT bool Dart_IsLibrary(Dart_Handle object);
  1799. DART_EXPORT bool Dart_IsType(Dart_Handle handle);
  1800. DART_EXPORT bool Dart_IsFunction(Dart_Handle handle);
  1801. DART_EXPORT bool Dart_IsVariable(Dart_Handle handle);
  1802. DART_EXPORT bool Dart_IsTypeVariable(Dart_Handle handle);
  1803. DART_EXPORT bool Dart_IsClosure(Dart_Handle object);
  1804. DART_EXPORT bool Dart_IsTypedData(Dart_Handle object);
  1805. DART_EXPORT bool Dart_IsByteBuffer(Dart_Handle object);
  1806. DART_EXPORT bool Dart_IsFuture(Dart_Handle object);
  1807. /*
  1808. * =========
  1809. * Instances
  1810. * =========
  1811. */
  1812. /*
  1813. * For the purposes of the embedding api, not all objects returned are
  1814. * Dart language objects. Within the api, we use the term 'Instance'
  1815. * to indicate handles which refer to true Dart language objects.
  1816. *
  1817. * TODO(turnidge): Reorganize the "Object" section above, pulling down
  1818. * any functions that more properly belong here. */
  1819. /**
  1820. * Gets the type of a Dart language object.
  1821. *
  1822. * \param instance Some Dart object.
  1823. *
  1824. * \return If no error occurs, the type is returned. Otherwise an
  1825. * error handle is returned.
  1826. */
  1827. DART_EXPORT Dart_Handle Dart_InstanceGetType(Dart_Handle instance);
  1828. /**
  1829. * Returns the name for the provided class type.
  1830. *
  1831. * \return A valid string handle if no error occurs during the
  1832. * operation.
  1833. */
  1834. DART_EXPORT Dart_Handle Dart_ClassName(Dart_Handle cls_type);
  1835. /**
  1836. * Returns the name for the provided function or method.
  1837. *
  1838. * \return A valid string handle if no error occurs during the
  1839. * operation.
  1840. */
  1841. DART_EXPORT Dart_Handle Dart_FunctionName(Dart_Handle function);
  1842. /**
  1843. * Returns a handle to the owner of a function.
  1844. *
  1845. * The owner of an instance method or a static method is its defining
  1846. * class. The owner of a top-level function is its defining
  1847. * library. The owner of the function of a non-implicit closure is the
  1848. * function of the method or closure that defines the non-implicit
  1849. * closure.
  1850. *
  1851. * \return A valid handle to the owner of the function, or an error
  1852. * handle if the argument is not a valid handle to a function.
  1853. */
  1854. DART_EXPORT Dart_Handle Dart_FunctionOwner(Dart_Handle function);
  1855. /**
  1856. * Determines whether a function handle refers to a static function
  1857. * of method.
  1858. *
  1859. * For the purposes of the embedding API, a top-level function is
  1860. * implicitly declared static.
  1861. *
  1862. * \param function A handle to a function or method declaration.
  1863. * \param is_static Returns whether the function or method is declared static.
  1864. *
  1865. * \return A valid handle if no error occurs during the operation.
  1866. */
  1867. DART_EXPORT Dart_Handle Dart_FunctionIsStatic(Dart_Handle function,
  1868. bool* is_static);
  1869. /**
  1870. * Is this object a closure resulting from a tear-off (closurized method)?
  1871. *
  1872. * Returns true for closures produced when an ordinary method is accessed
  1873. * through a getter call. Returns false otherwise, in particular for closures
  1874. * produced from local function declarations.
  1875. *
  1876. * \param object Some Object.
  1877. *
  1878. * \return true if Object is a tear-off.
  1879. */
  1880. DART_EXPORT bool Dart_IsTearOff(Dart_Handle object);
  1881. /**
  1882. * Retrieves the function of a closure.
  1883. *
  1884. * \return A handle to the function of the closure, or an error handle if the
  1885. * argument is not a closure.
  1886. */
  1887. DART_EXPORT Dart_Handle Dart_ClosureFunction(Dart_Handle closure);
  1888. /**
  1889. * Returns a handle to the library which contains class.
  1890. *
  1891. * \return A valid handle to the library with owns class, null if the class
  1892. * has no library or an error handle if the argument is not a valid handle
  1893. * to a class type.
  1894. */
  1895. DART_EXPORT Dart_Handle Dart_ClassLibrary(Dart_Handle cls_type);
  1896. /*
  1897. * =============================
  1898. * Numbers, Integers and Doubles
  1899. * =============================
  1900. */
  1901. /**
  1902. * Does this Integer fit into a 64-bit signed integer?
  1903. *
  1904. * \param integer An integer.
  1905. * \param fits Returns true if the integer fits into a 64-bit signed integer.
  1906. *
  1907. * \return A valid handle if no error occurs during the operation.
  1908. */
  1909. DART_EXPORT Dart_Handle Dart_IntegerFitsIntoInt64(Dart_Handle integer,
  1910. bool* fits);
  1911. /**
  1912. * Does this Integer fit into a 64-bit unsigned integer?
  1913. *
  1914. * \param integer An integer.
  1915. * \param fits Returns true if the integer fits into a 64-bit unsigned integer.
  1916. *
  1917. * \return A valid handle if no error occurs during the operation.
  1918. */
  1919. DART_EXPORT Dart_Handle Dart_IntegerFitsIntoUint64(Dart_Handle integer,
  1920. bool* fits);
  1921. /**
  1922. * Returns an Integer with the provided value.
  1923. *
  1924. * \param value The value of the integer.
  1925. *
  1926. * \return The Integer object if no error occurs. Otherwise returns
  1927. * an error handle.
  1928. */
  1929. DART_EXPORT Dart_Handle Dart_NewInteger(int64_t value);
  1930. /**
  1931. * Returns an Integer with the provided value.
  1932. *
  1933. * \param value The unsigned value of the integer.
  1934. *
  1935. * \return The Integer object if no error occurs. Otherwise returns
  1936. * an error handle.
  1937. */
  1938. DART_EXPORT Dart_Handle Dart_NewIntegerFromUint64(uint64_t value);
  1939. /**
  1940. * Returns an Integer with the provided value.
  1941. *
  1942. * \param value The value of the integer represented as a C string
  1943. * containing a hexadecimal number.
  1944. *
  1945. * \return The Integer object if no error occurs. Otherwise returns
  1946. * an error handle.
  1947. */
  1948. DART_EXPORT Dart_Handle Dart_NewIntegerFromHexCString(const char* value);
  1949. /**
  1950. * Gets the value of an Integer.
  1951. *
  1952. * The integer must fit into a 64-bit signed integer, otherwise an error occurs.
  1953. *
  1954. * \param integer An Integer.
  1955. * \param value Returns the value of the Integer.
  1956. *
  1957. * \return A valid handle if no error occurs during the operation.
  1958. */
  1959. DART_EXPORT Dart_Handle Dart_IntegerToInt64(Dart_Handle integer,
  1960. int64_t* value);
  1961. /**
  1962. * Gets the value of an Integer.
  1963. *
  1964. * The integer must fit into a 64-bit unsigned integer, otherwise an
  1965. * error occurs.
  1966. *
  1967. * \param integer An Integer.
  1968. * \param value Returns the value of the Integer.
  1969. *
  1970. * \return A valid handle if no error occurs during the operation.
  1971. */
  1972. DART_EXPORT Dart_Handle Dart_IntegerToUint64(Dart_Handle integer,
  1973. uint64_t* value);
  1974. /**
  1975. * Gets the value of an integer as a hexadecimal C string.
  1976. *
  1977. * \param integer An Integer.
  1978. * \param value Returns the value of the Integer as a hexadecimal C
  1979. * string. This C string is scope allocated and is only valid until
  1980. * the next call to Dart_ExitScope.
  1981. *
  1982. * \return A valid handle if no error occurs during the operation.
  1983. */
  1984. DART_EXPORT Dart_Handle Dart_IntegerToHexCString(Dart_Handle integer,
  1985. const char** value);
  1986. /**
  1987. * Returns a Double with the provided value.
  1988. *
  1989. * \param value A double.
  1990. *
  1991. * \return The Double object if no error occurs. Otherwise returns
  1992. * an error handle.
  1993. */
  1994. DART_EXPORT Dart_Handle Dart_NewDouble(double value);
  1995. /**
  1996. * Gets the value of a Double
  1997. *
  1998. * \param double_obj A Double
  1999. * \param value Returns the value of the Double.
  2000. *
  2001. * \return A valid handle if no error occurs during the operation.
  2002. */
  2003. DART_EXPORT Dart_Handle Dart_DoubleValue(Dart_Handle double_obj, double* value);
  2004. /**
  2005. * Returns a closure of static function 'function_name' in the class 'class_name'
  2006. * in the exported namespace of specified 'library'.
  2007. *
  2008. * \param library Library object
  2009. * \param cls_type Type object representing a Class
  2010. * \param function_name Name of the static function in the class
  2011. *
  2012. * \return A valid Dart instance if no error occurs during the operation.
  2013. */
  2014. DART_EXPORT Dart_Handle Dart_GetStaticMethodClosure(Dart_Handle library,
  2015. Dart_Handle cls_type,
  2016. Dart_Handle function_name);
  2017. /*
  2018. * ========
  2019. * Booleans
  2020. * ========
  2021. */
  2022. /**
  2023. * Returns the True object.
  2024. *
  2025. * Requires there to be a current isolate.
  2026. *
  2027. * \return A handle to the True object.
  2028. */
  2029. DART_EXPORT Dart_Handle Dart_True(void);
  2030. /**
  2031. * Returns the False object.
  2032. *
  2033. * Requires there to be a current isolate.
  2034. *
  2035. * \return A handle to the False object.
  2036. */
  2037. DART_EXPORT Dart_Handle Dart_False(void);
  2038. /**
  2039. * Returns a Boolean with the provided value.
  2040. *
  2041. * \param value true or false.
  2042. *
  2043. * \return The Boolean object if no error occurs. Otherwise returns
  2044. * an error handle.
  2045. */
  2046. DART_EXPORT Dart_Handle Dart_NewBoolean(bool value);
  2047. /**
  2048. * Gets the value of a Boolean
  2049. *
  2050. * \param boolean_obj A Boolean
  2051. * \param value Returns the value of the Boolean.
  2052. *
  2053. * \return A valid handle if no error occurs during the operation.
  2054. */
  2055. DART_EXPORT Dart_Handle Dart_BooleanValue(Dart_Handle boolean_obj, bool* value);
  2056. /*
  2057. * =======
  2058. * Strings
  2059. * =======
  2060. */
  2061. /**
  2062. * Gets the length of a String.
  2063. *
  2064. * \param str A String.
  2065. * \param length Returns the length of the String.
  2066. *
  2067. * \return A valid handle if no error occurs during the operation.
  2068. */
  2069. DART_EXPORT Dart_Handle Dart_StringLength(Dart_Handle str, intptr_t* length);
  2070. /**
  2071. * Returns a String built from the provided C string
  2072. * (There is an implicit assumption that the C string passed in contains
  2073. * UTF-8 encoded characters and '\0' is considered as a termination
  2074. * character).
  2075. *
  2076. * \param str A C String
  2077. *
  2078. * \return The String object if no error occurs. Otherwise returns
  2079. * an error handle.
  2080. */
  2081. DART_EXPORT Dart_Handle Dart_NewStringFromCString(const char* str);
  2082. /* TODO(turnidge): Document what happens when we run out of memory
  2083. * during this call. */
  2084. /**
  2085. * Returns a String built from an array of UTF-8 encoded characters.
  2086. *
  2087. * \param utf8_array An array of UTF-8 encoded characters.
  2088. * \param length The length of the codepoints array.
  2089. *
  2090. * \return The String object if no error occurs. Otherwise returns
  2091. * an error handle.
  2092. */
  2093. DART_EXPORT Dart_Handle Dart_NewStringFromUTF8(const uint8_t* utf8_array,
  2094. intptr_t length);
  2095. /**
  2096. * Returns a String built from an array of UTF-16 encoded characters.
  2097. *
  2098. * \param utf16_array An array of UTF-16 encoded characters.
  2099. * \param length The length of the codepoints array.
  2100. *
  2101. * \return The String object if no error occurs. Otherwise returns
  2102. * an error handle.
  2103. */
  2104. DART_EXPORT Dart_Handle Dart_NewStringFromUTF16(const uint16_t* utf16_array,
  2105. intptr_t length);
  2106. /**
  2107. * Returns a String built from an array of UTF-32 encoded characters.
  2108. *
  2109. * \param utf32_array An array of UTF-32 encoded characters.
  2110. * \param length The length of the codepoints array.
  2111. *
  2112. * \return The String object if no error occurs. Otherwise returns
  2113. * an error handle.
  2114. */
  2115. DART_EXPORT Dart_Handle Dart_NewStringFromUTF32(const int32_t* utf32_array,
  2116. intptr_t length);
  2117. /**
  2118. * Returns a String which references an external array of
  2119. * Latin-1 (ISO-8859-1) encoded characters.
  2120. *
  2121. * \param latin1_array Array of Latin-1 encoded characters. This must not move.
  2122. * \param length The length of the characters array.
  2123. * \param peer An external pointer to associate with this string.
  2124. * \param external_allocation_size The number of externally allocated
  2125. * bytes for peer. Used to inform the garbage collector.
  2126. * \param callback A callback to be called when this string is finalized.
  2127. *
  2128. * \return The String object if no error occurs. Otherwise returns
  2129. * an error handle.
  2130. */
  2131. DART_EXPORT Dart_Handle
  2132. Dart_NewExternalLatin1String(const uint8_t* latin1_array,
  2133. intptr_t length,
  2134. void* peer,
  2135. intptr_t external_allocation_size,
  2136. Dart_HandleFinalizer callback);
  2137. /**
  2138. * Returns a String which references an external array of UTF-16 encoded
  2139. * characters.
  2140. *
  2141. * \param utf16_array An array of UTF-16 encoded characters. This must not move.
  2142. * \param length The length of the characters array.
  2143. * \param peer An external pointer to associate with this string.
  2144. * \param external_allocation_size The number of externally allocated
  2145. * bytes for peer. Used to inform the garbage collector.
  2146. * \param callback A callback to be called when this string is finalized.
  2147. *
  2148. * \return The String object if no error occurs. Otherwise returns
  2149. * an error handle.
  2150. */
  2151. DART_EXPORT Dart_Handle
  2152. Dart_NewExternalUTF16String(const uint16_t* utf16_array,
  2153. intptr_t length,
  2154. void* peer,
  2155. intptr_t external_allocation_size,
  2156. Dart_HandleFinalizer callback);
  2157. /**
  2158. * Gets the C string representation of a String.
  2159. * (It is a sequence of UTF-8 encoded values with a '\0' termination.)
  2160. *
  2161. * \param str A string.
  2162. * \param cstr Returns the String represented as a C string.
  2163. * This C string is scope allocated and is only valid until
  2164. * the next call to Dart_ExitScope.
  2165. *
  2166. * \return A valid handle if no error occurs during the operation.
  2167. */
  2168. DART_EXPORT Dart_Handle Dart_StringToCString(Dart_Handle str,
  2169. const char** cstr);
  2170. /**
  2171. * Gets a UTF-8 encoded representation of a String.
  2172. *
  2173. * Any unpaired surrogate code points in the string will be converted as
  2174. * replacement characters (U+FFFD, 0xEF 0xBF 0xBD in UTF-8). If you need
  2175. * to preserve unpaired surrogates, use the Dart_StringToUTF16 function.
  2176. *
  2177. * \param str A string.
  2178. * \param utf8_array Returns the String represented as UTF-8 code
  2179. * units. This UTF-8 array is scope allocated and is only valid
  2180. * until the next call to Dart_ExitScope.
  2181. * \param length Used to return the length of the array which was
  2182. * actually used.
  2183. *
  2184. * \return A valid handle if no error occurs during the operation.
  2185. */
  2186. DART_EXPORT Dart_Handle Dart_StringToUTF8(Dart_Handle str,
  2187. uint8_t** utf8_array,
  2188. intptr_t* length);
  2189. /**
  2190. * Gets the data corresponding to the string object. This function returns
  2191. * the data only for Latin-1 (ISO-8859-1) string objects. For all other
  2192. * string objects it returns an error.
  2193. *
  2194. * \param str A string.
  2195. * \param latin1_array An array allocated by the caller, used to return
  2196. * the string data.
  2197. * \param length Used to pass in the length of the provided array.
  2198. * Used to return the length of the array which was actually used.
  2199. *
  2200. * \return A valid handle if no error occurs during the operation.
  2201. */
  2202. DART_EXPORT Dart_Handle Dart_StringToLatin1(Dart_Handle str,
  2203. uint8_t* latin1_array,
  2204. intptr_t* length);
  2205. /**
  2206. * Gets the UTF-16 encoded representation of a string.
  2207. *
  2208. * \param str A string.
  2209. * \param utf16_array An array allocated by the caller, used to return
  2210. * the array of UTF-16 encoded characters.
  2211. * \param length Used to pass in the length of the provided array.
  2212. * Used to return the length of the array which was actually used.
  2213. *
  2214. * \return A valid handle if no error occurs during the operation.
  2215. */
  2216. DART_EXPORT Dart_Handle Dart_StringToUTF16(Dart_Handle str,
  2217. uint16_t* utf16_array,
  2218. intptr_t* length);
  2219. /**
  2220. * Gets the storage size in bytes of a String.
  2221. *
  2222. * \param str A String.
  2223. * \param size Returns the storage size in bytes of the String.
  2224. * This is the size in bytes needed to store the String.
  2225. *
  2226. * \return A valid handle if no error occurs during the operation.
  2227. */
  2228. DART_EXPORT Dart_Handle Dart_StringStorageSize(Dart_Handle str, intptr_t* size);
  2229. /**
  2230. * Retrieves some properties associated with a String.
  2231. * Properties retrieved are:
  2232. * - character size of the string (one or two byte)
  2233. * - length of the string
  2234. * - peer pointer of string if it is an external string.
  2235. * \param str A String.
  2236. * \param char_size Returns the character size of the String.
  2237. * \param str_len Returns the length of the String.
  2238. * \param peer Returns the peer pointer associated with the String or 0 if
  2239. * there is no peer pointer for it.
  2240. * \return Success if no error occurs. Otherwise returns
  2241. * an error handle.
  2242. */
  2243. DART_EXPORT Dart_Handle Dart_StringGetProperties(Dart_Handle str,
  2244. intptr_t* char_size,
  2245. intptr_t* str_len,
  2246. void** peer);
  2247. /*
  2248. * =====
  2249. * Lists
  2250. * =====
  2251. */
  2252. /**
  2253. * Returns a List<dynamic> of the desired length.
  2254. *
  2255. * \param length The length of the list.
  2256. *
  2257. * \return The List object if no error occurs. Otherwise returns
  2258. * an error handle.
  2259. */
  2260. DART_EXPORT Dart_Handle Dart_NewList(intptr_t length);
  2261. typedef enum {
  2262. Dart_CoreType_Dynamic,
  2263. Dart_CoreType_Int,
  2264. Dart_CoreType_String,
  2265. } Dart_CoreType_Id;
  2266. // TODO(bkonyi): convert this to use nullable types once NNBD is enabled.
  2267. /**
  2268. * Returns a List of the desired length with the desired legacy element type.
  2269. *
  2270. * \param element_type_id The type of elements of the list.
  2271. * \param length The length of the list.
  2272. *
  2273. * \return The List object if no error occurs. Otherwise returns an error
  2274. * handle.
  2275. */
  2276. DART_EXPORT Dart_Handle Dart_NewListOf(Dart_CoreType_Id element_type_id,
  2277. intptr_t length);
  2278. /**
  2279. * Returns a List of the desired length with the desired element type.
  2280. *
  2281. * \param element_type Handle to a nullable type object. E.g., from
  2282. * Dart_GetType or Dart_GetNullableType.
  2283. *
  2284. * \param length The length of the list.
  2285. *
  2286. * \return The List object if no error occurs. Otherwise returns
  2287. * an error handle.
  2288. */
  2289. DART_EXPORT Dart_Handle Dart_NewListOfType(Dart_Handle element_type,
  2290. intptr_t length);
  2291. /**
  2292. * Returns a List of the desired length with the desired element type, filled
  2293. * with the provided object.
  2294. *
  2295. * \param element_type Handle to a type object. E.g., from Dart_GetType.
  2296. *
  2297. * \param fill_object Handle to an object of type 'element_type' that will be
  2298. * used to populate the list. This parameter can only be Dart_Null() if the
  2299. * length of the list is 0 or 'element_type' is a nullable type.
  2300. *
  2301. * \param length The length of the list.
  2302. *
  2303. * \return The List object if no error occurs. Otherwise returns
  2304. * an error handle.
  2305. */
  2306. DART_EXPORT Dart_Handle Dart_NewListOfTypeFilled(Dart_Handle element_type,
  2307. Dart_Handle fill_object,
  2308. intptr_t length);
  2309. /**
  2310. * Gets the length of a List.
  2311. *
  2312. * May generate an unhandled exception error.
  2313. *
  2314. * \param list A List.
  2315. * \param length Returns the length of the List.
  2316. *
  2317. * \return A valid handle if no error occurs during the operation.
  2318. */
  2319. DART_EXPORT Dart_Handle Dart_ListLength(Dart_Handle list, intptr_t* length);
  2320. /**
  2321. * Gets the Object at some index of a List.
  2322. *
  2323. * If the index is out of bounds, an error occurs.
  2324. *
  2325. * May generate an unhandled exception error.
  2326. *
  2327. * \param list A List.
  2328. * \param index A valid index into the List.
  2329. *
  2330. * \return The Object in the List at the specified index if no error
  2331. * occurs. Otherwise returns an error handle.
  2332. */
  2333. DART_EXPORT Dart_Handle Dart_ListGetAt(Dart_Handle list, intptr_t index);
  2334. /**
  2335. * Gets a range of Objects from a List.
  2336. *
  2337. * If any of the requested index values are out of bounds, an error occurs.
  2338. *
  2339. * May generate an unhandled exception error.
  2340. *
  2341. * \param list A List.
  2342. * \param offset The offset of the first item to get.
  2343. * \param length The number of items to get.
  2344. * \param result A pointer to fill with the objects.
  2345. *
  2346. * \return Success if no error occurs during the operation.
  2347. */
  2348. DART_EXPORT Dart_Handle Dart_ListGetRange(Dart_Handle list,
  2349. intptr_t offset,
  2350. intptr_t length,
  2351. Dart_Handle* result);
  2352. /**
  2353. * Sets the Object at some index of a List.
  2354. *
  2355. * If the index is out of bounds, an error occurs.
  2356. *
  2357. * May generate an unhandled exception error.
  2358. *
  2359. * \param list A List.
  2360. * \param index A valid index into the List.
  2361. * \param value The Object to put in the List.
  2362. *
  2363. * \return A valid handle if no error occurs during the operation.
  2364. */
  2365. DART_EXPORT Dart_Handle Dart_ListSetAt(Dart_Handle list,
  2366. intptr_t index,
  2367. Dart_Handle value);
  2368. /**
  2369. * May generate an unhandled exception error.
  2370. */
  2371. DART_EXPORT Dart_Handle Dart_ListGetAsBytes(Dart_Handle list,
  2372. intptr_t offset,
  2373. uint8_t* native_array,
  2374. intptr_t length);
  2375. /**
  2376. * May generate an unhandled exception error.
  2377. */
  2378. DART_EXPORT Dart_Handle Dart_ListSetAsBytes(Dart_Handle list,
  2379. intptr_t offset,
  2380. const uint8_t* native_array,
  2381. intptr_t length);
  2382. /*
  2383. * ====
  2384. * Maps
  2385. * ====
  2386. */
  2387. /**
  2388. * Gets the Object at some key of a Map.
  2389. *
  2390. * May generate an unhandled exception error.
  2391. *
  2392. * \param map A Map.
  2393. * \param key An Object.
  2394. *
  2395. * \return The value in the map at the specified key, null if the map does not
  2396. * contain the key, or an error handle.
  2397. */
  2398. DART_EXPORT Dart_Handle Dart_MapGetAt(Dart_Handle map, Dart_Handle key);
  2399. /**
  2400. * Returns whether the Map contains a given key.
  2401. *
  2402. * May generate an unhandled exception error.
  2403. *
  2404. * \param map A Map.
  2405. *
  2406. * \return A handle on a boolean indicating whether map contains the key.
  2407. * Otherwise returns an error handle.
  2408. */
  2409. DART_EXPORT Dart_Handle Dart_MapContainsKey(Dart_Handle map, Dart_Handle key);
  2410. /**
  2411. * Gets the list of keys of a Map.
  2412. *
  2413. * May generate an unhandled exception error.
  2414. *
  2415. * \param map A Map.
  2416. *
  2417. * \return The list of key Objects if no error occurs. Otherwise returns an
  2418. * error handle.
  2419. */
  2420. DART_EXPORT Dart_Handle Dart_MapKeys(Dart_Handle map);
  2421. /*
  2422. * ==========
  2423. * Typed Data
  2424. * ==========
  2425. */
  2426. typedef enum {
  2427. Dart_TypedData_kByteData = 0,
  2428. Dart_TypedData_kInt8,
  2429. Dart_TypedData_kUint8,
  2430. Dart_TypedData_kUint8Clamped,
  2431. Dart_TypedData_kInt16,
  2432. Dart_TypedData_kUint16,
  2433. Dart_TypedData_kInt32,
  2434. Dart_TypedData_kUint32,
  2435. Dart_TypedData_kInt64,
  2436. Dart_TypedData_kUint64,
  2437. Dart_TypedData_kFloat32,
  2438. Dart_TypedData_kFloat64,
  2439. Dart_TypedData_kInt32x4,
  2440. Dart_TypedData_kFloat32x4,
  2441. Dart_TypedData_kFloat64x2,
  2442. Dart_TypedData_kInvalid
  2443. } Dart_TypedData_Type;
  2444. /**
  2445. * Return type if this object is a TypedData object.
  2446. *
  2447. * \return kInvalid if the object is not a TypedData object or the appropriate
  2448. * Dart_TypedData_Type.
  2449. */
  2450. DART_EXPORT Dart_TypedData_Type Dart_GetTypeOfTypedData(Dart_Handle object);
  2451. /**
  2452. * Return type if this object is an external TypedData object.
  2453. *
  2454. * \return kInvalid if the object is not an external TypedData object or
  2455. * the appropriate Dart_TypedData_Type.
  2456. */
  2457. DART_EXPORT Dart_TypedData_Type
  2458. Dart_GetTypeOfExternalTypedData(Dart_Handle object);
  2459. /**
  2460. * Returns a TypedData object of the desired length and type.
  2461. *
  2462. * \param type The type of the TypedData object.
  2463. * \param length The length of the TypedData object (length in type units).
  2464. *
  2465. * \return The TypedData object if no error occurs. Otherwise returns
  2466. * an error handle.
  2467. */
  2468. DART_EXPORT Dart_Handle Dart_NewTypedData(Dart_TypedData_Type type,
  2469. intptr_t length);
  2470. /**
  2471. * Returns a TypedData object which references an external data array.
  2472. *
  2473. * \param type The type of the data array.
  2474. * \param data A data array. This array must not move.
  2475. * \param length The length of the data array (length in type units).
  2476. *
  2477. * \return The TypedData object if no error occurs. Otherwise returns
  2478. * an error handle.
  2479. */
  2480. DART_EXPORT Dart_Handle Dart_NewExternalTypedData(Dart_TypedData_Type type,
  2481. void* data,
  2482. intptr_t length);
  2483. /**
  2484. * Returns a TypedData object which references an external data array.
  2485. *
  2486. * \param type The type of the data array.
  2487. * \param data A data array. This array must not move.
  2488. * \param length The length of the data array (length in type units).
  2489. * \param peer A pointer to a native object or NULL. This value is
  2490. * provided to callback when it is invoked.
  2491. * \param external_allocation_size The number of externally allocated
  2492. * bytes for peer. Used to inform the garbage collector.
  2493. * \param callback A function pointer that will be invoked sometime
  2494. * after the object is garbage collected, unless the handle has been deleted.
  2495. * A valid callback needs to be specified it cannot be NULL.
  2496. *
  2497. * \return The TypedData object if no error occurs. Otherwise returns
  2498. * an error handle.
  2499. */
  2500. DART_EXPORT Dart_Handle
  2501. Dart_NewExternalTypedDataWithFinalizer(Dart_TypedData_Type type,
  2502. void* data,
  2503. intptr_t length,
  2504. void* peer,
  2505. intptr_t external_allocation_size,
  2506. Dart_HandleFinalizer callback);
  2507. DART_EXPORT Dart_Handle Dart_NewUnmodifiableExternalTypedDataWithFinalizer(
  2508. Dart_TypedData_Type type,
  2509. const void* data,
  2510. intptr_t length,
  2511. void* peer,
  2512. intptr_t external_allocation_size,
  2513. Dart_HandleFinalizer callback);
  2514. /**
  2515. * Returns a ByteBuffer object for the typed data.
  2516. *
  2517. * \param typed_data The TypedData object.
  2518. *
  2519. * \return The ByteBuffer object if no error occurs. Otherwise returns
  2520. * an error handle.
  2521. */
  2522. DART_EXPORT Dart_Handle Dart_NewByteBuffer(Dart_Handle typed_data);
  2523. /**
  2524. * Acquires access to the internal data address of a TypedData object.
  2525. *
  2526. * \param object The typed data object whose internal data address is to
  2527. * be accessed.
  2528. * \param type The type of the object is returned here.
  2529. * \param data The internal data address is returned here.
  2530. * \param len Size of the typed array is returned here.
  2531. *
  2532. * Notes:
  2533. * When the internal address of the object is acquired any calls to a
  2534. * Dart API function that could potentially allocate an object or run
  2535. * any Dart code will return an error.
  2536. *
  2537. * Any Dart API functions for accessing the data should not be called
  2538. * before the corresponding release. In particular, the object should
  2539. * not be acquired again before its release. This leads to undefined
  2540. * behavior.
  2541. *
  2542. * \return Success if the internal data address is acquired successfully.
  2543. * Otherwise, returns an error handle.
  2544. */
  2545. DART_EXPORT Dart_Handle Dart_TypedDataAcquireData(Dart_Handle object,
  2546. Dart_TypedData_Type* type,
  2547. void** data,
  2548. intptr_t* len);
  2549. /**
  2550. * Releases access to the internal data address that was acquired earlier using
  2551. * Dart_TypedDataAcquireData.
  2552. *
  2553. * \param object The typed data object whose internal data address is to be
  2554. * released.
  2555. *
  2556. * \return Success if the internal data address is released successfully.
  2557. * Otherwise, returns an error handle.
  2558. */
  2559. DART_EXPORT Dart_Handle Dart_TypedDataReleaseData(Dart_Handle object);
  2560. /**
  2561. * Returns the TypedData object associated with the ByteBuffer object.
  2562. *
  2563. * \param byte_buffer The ByteBuffer object.
  2564. *
  2565. * \return The TypedData object if no error occurs. Otherwise returns
  2566. * an error handle.
  2567. */
  2568. DART_EXPORT Dart_Handle Dart_GetDataFromByteBuffer(Dart_Handle byte_buffer);
  2569. /*
  2570. * ============================================================
  2571. * Invoking Constructors, Methods, Closures and Field accessors
  2572. * ============================================================
  2573. */
  2574. /**
  2575. * Invokes a constructor, creating a new object.
  2576. *
  2577. * This function allows hidden constructors (constructors with leading
  2578. * underscores) to be called.
  2579. *
  2580. * \param type Type of object to be constructed.
  2581. * \param constructor_name The name of the constructor to invoke. Use
  2582. * Dart_Null() or Dart_EmptyString() to invoke the unnamed constructor.
  2583. * This name should not include the name of the class.
  2584. * \param number_of_arguments Size of the arguments array.
  2585. * \param arguments An array of arguments to the constructor.
  2586. *
  2587. * \return If the constructor is called and completes successfully,
  2588. * then the new object. If an error occurs during execution, then an
  2589. * error handle is returned.
  2590. */
  2591. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  2592. Dart_New(Dart_Handle type,
  2593. Dart_Handle constructor_name,
  2594. int number_of_arguments,
  2595. Dart_Handle* arguments);
  2596. /**
  2597. * Allocate a new object without invoking a constructor.
  2598. *
  2599. * \param type The type of an object to be allocated.
  2600. *
  2601. * \return The new object. If an error occurs during execution, then an
  2602. * error handle is returned.
  2603. */
  2604. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_Allocate(Dart_Handle type);
  2605. /**
  2606. * Allocate a new object without invoking a constructor, and sets specified
  2607. * native fields.
  2608. *
  2609. * \param type The type of an object to be allocated.
  2610. * \param num_native_fields The number of native fields to set.
  2611. * \param native_fields An array containing the value of native fields.
  2612. *
  2613. * \return The new object. If an error occurs during execution, then an
  2614. * error handle is returned.
  2615. */
  2616. DART_EXPORT Dart_Handle
  2617. Dart_AllocateWithNativeFields(Dart_Handle type,
  2618. intptr_t num_native_fields,
  2619. const intptr_t* native_fields);
  2620. /**
  2621. * Invokes a method or function.
  2622. *
  2623. * The 'target' parameter may be an object, type, or library. If
  2624. * 'target' is an object, then this function will invoke an instance
  2625. * method. If 'target' is a type, then this function will invoke a
  2626. * static method. If 'target' is a library, then this function will
  2627. * invoke a top-level function from that library.
  2628. * NOTE: This API call cannot be used to invoke methods of a type object.
  2629. *
  2630. * This function ignores visibility (leading underscores in names).
  2631. *
  2632. * May generate an unhandled exception error.
  2633. *
  2634. * \param target An object, type, or library.
  2635. * \param name The name of the function or method to invoke.
  2636. * \param number_of_arguments Size of the arguments array.
  2637. * \param arguments An array of arguments to the function.
  2638. *
  2639. * \return If the function or method is called and completes
  2640. * successfully, then the return value is returned. If an error
  2641. * occurs during execution, then an error handle is returned.
  2642. */
  2643. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  2644. Dart_Invoke(Dart_Handle target,
  2645. Dart_Handle name,
  2646. int number_of_arguments,
  2647. Dart_Handle* arguments);
  2648. /* TODO(turnidge): Document how to invoke operators. */
  2649. /**
  2650. * Invokes a Closure with the given arguments.
  2651. *
  2652. * May generate an unhandled exception error.
  2653. *
  2654. * \return If no error occurs during execution, then the result of
  2655. * invoking the closure is returned. If an error occurs during
  2656. * execution, then an error handle is returned.
  2657. */
  2658. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  2659. Dart_InvokeClosure(Dart_Handle closure,
  2660. int number_of_arguments,
  2661. Dart_Handle* arguments);
  2662. /**
  2663. * Invokes a Generative Constructor on an object that was previously
  2664. * allocated using Dart_Allocate/Dart_AllocateWithNativeFields.
  2665. *
  2666. * The 'object' parameter must be an object.
  2667. *
  2668. * This function ignores visibility (leading underscores in names).
  2669. *
  2670. * May generate an unhandled exception error.
  2671. *
  2672. * \param object An object.
  2673. * \param name The name of the constructor to invoke.
  2674. * Use Dart_Null() or Dart_EmptyString() to invoke the unnamed constructor.
  2675. * \param number_of_arguments Size of the arguments array.
  2676. * \param arguments An array of arguments to the function.
  2677. *
  2678. * \return If the constructor is called and completes
  2679. * successfully, then the object is returned. If an error
  2680. * occurs during execution, then an error handle is returned.
  2681. */
  2682. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  2683. Dart_InvokeConstructor(Dart_Handle object,
  2684. Dart_Handle name,
  2685. int number_of_arguments,
  2686. Dart_Handle* arguments);
  2687. /**
  2688. * Gets the value of a field.
  2689. *
  2690. * The 'container' parameter may be an object, type, or library. If
  2691. * 'container' is an object, then this function will access an
  2692. * instance field. If 'container' is a type, then this function will
  2693. * access a static field. If 'container' is a library, then this
  2694. * function will access a top-level variable.
  2695. * NOTE: This API call cannot be used to access fields of a type object.
  2696. *
  2697. * This function ignores field visibility (leading underscores in names).
  2698. *
  2699. * May generate an unhandled exception error.
  2700. *
  2701. * \param container An object, type, or library.
  2702. * \param name A field name.
  2703. *
  2704. * \return If no error occurs, then the value of the field is
  2705. * returned. Otherwise an error handle is returned.
  2706. */
  2707. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  2708. Dart_GetField(Dart_Handle container, Dart_Handle name);
  2709. /**
  2710. * Sets the value of a field.
  2711. *
  2712. * The 'container' parameter may actually be an object, type, or
  2713. * library. If 'container' is an object, then this function will
  2714. * access an instance field. If 'container' is a type, then this
  2715. * function will access a static field. If 'container' is a library,
  2716. * then this function will access a top-level variable.
  2717. * NOTE: This API call cannot be used to access fields of a type object.
  2718. *
  2719. * This function ignores field visibility (leading underscores in names).
  2720. *
  2721. * May generate an unhandled exception error.
  2722. *
  2723. * \param container An object, type, or library.
  2724. * \param name A field name.
  2725. * \param value The new field value.
  2726. *
  2727. * \return A valid handle if no error occurs.
  2728. */
  2729. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  2730. Dart_SetField(Dart_Handle container, Dart_Handle name, Dart_Handle value);
  2731. /*
  2732. * ==========
  2733. * Exceptions
  2734. * ==========
  2735. */
  2736. /*
  2737. * TODO(turnidge): Remove these functions from the api and replace all
  2738. * uses with Dart_NewUnhandledExceptionError. */
  2739. /**
  2740. * Throws an exception.
  2741. *
  2742. * This function causes a Dart language exception to be thrown. This
  2743. * will proceed in the standard way, walking up Dart frames until an
  2744. * appropriate 'catch' block is found, executing 'finally' blocks,
  2745. * etc.
  2746. *
  2747. * If an error handle is passed into this function, the error is
  2748. * propagated immediately. See Dart_PropagateError for a discussion
  2749. * of error propagation.
  2750. *
  2751. * If successful, this function does not return. Note that this means
  2752. * that the destructors of any stack-allocated C++ objects will not be
  2753. * called. If there are no Dart frames on the stack, an error occurs.
  2754. *
  2755. * \return An error handle if the exception was not thrown.
  2756. * Otherwise the function does not return.
  2757. */
  2758. DART_EXPORT Dart_Handle Dart_ThrowException(Dart_Handle exception);
  2759. /**
  2760. * Rethrows an exception.
  2761. *
  2762. * Rethrows an exception, unwinding all dart frames on the stack. If
  2763. * successful, this function does not return. Note that this means
  2764. * that the destructors of any stack-allocated C++ objects will not be
  2765. * called. If there are no Dart frames on the stack, an error occurs.
  2766. *
  2767. * \return An error handle if the exception was not thrown.
  2768. * Otherwise the function does not return.
  2769. */
  2770. DART_EXPORT Dart_Handle Dart_ReThrowException(Dart_Handle exception,
  2771. Dart_Handle stacktrace);
  2772. /*
  2773. * ===========================
  2774. * Native fields and functions
  2775. * ===========================
  2776. */
  2777. /**
  2778. * Gets the number of native instance fields in an object.
  2779. */
  2780. DART_EXPORT Dart_Handle Dart_GetNativeInstanceFieldCount(Dart_Handle obj,
  2781. int* count);
  2782. /**
  2783. * Gets the value of a native field.
  2784. *
  2785. * TODO(turnidge): Document.
  2786. */
  2787. DART_EXPORT Dart_Handle Dart_GetNativeInstanceField(Dart_Handle obj,
  2788. int index,
  2789. intptr_t* value);
  2790. /**
  2791. * Sets the value of a native field.
  2792. *
  2793. * TODO(turnidge): Document.
  2794. */
  2795. DART_EXPORT Dart_Handle Dart_SetNativeInstanceField(Dart_Handle obj,
  2796. int index,
  2797. intptr_t value);
  2798. /**
  2799. * The arguments to a native function.
  2800. *
  2801. * This object is passed to a native function to represent its
  2802. * arguments and return value. It allows access to the arguments to a
  2803. * native function by index. It also allows the return value of a
  2804. * native function to be set.
  2805. */
  2806. typedef struct _Dart_NativeArguments* Dart_NativeArguments;
  2807. /**
  2808. * Extracts current isolate group data from the native arguments structure.
  2809. */
  2810. DART_EXPORT void* Dart_GetNativeIsolateGroupData(Dart_NativeArguments args);
  2811. typedef enum {
  2812. Dart_NativeArgument_kBool = 0,
  2813. Dart_NativeArgument_kInt32,
  2814. Dart_NativeArgument_kUint32,
  2815. Dart_NativeArgument_kInt64,
  2816. Dart_NativeArgument_kUint64,
  2817. Dart_NativeArgument_kDouble,
  2818. Dart_NativeArgument_kString,
  2819. Dart_NativeArgument_kInstance,
  2820. Dart_NativeArgument_kNativeFields,
  2821. } Dart_NativeArgument_Type;
  2822. typedef struct _Dart_NativeArgument_Descriptor {
  2823. uint8_t type;
  2824. uint8_t index;
  2825. } Dart_NativeArgument_Descriptor;
  2826. typedef union _Dart_NativeArgument_Value {
  2827. bool as_bool;
  2828. int32_t as_int32;
  2829. uint32_t as_uint32;
  2830. int64_t as_int64;
  2831. uint64_t as_uint64;
  2832. double as_double;
  2833. struct {
  2834. Dart_Handle dart_str;
  2835. void* peer;
  2836. } as_string;
  2837. struct {
  2838. intptr_t num_fields;
  2839. intptr_t* values;
  2840. } as_native_fields;
  2841. Dart_Handle as_instance;
  2842. } Dart_NativeArgument_Value;
  2843. enum {
  2844. kNativeArgNumberPos = 0,
  2845. kNativeArgNumberSize = 8,
  2846. kNativeArgTypePos = kNativeArgNumberPos + kNativeArgNumberSize,
  2847. kNativeArgTypeSize = 8,
  2848. };
  2849. #define BITMASK(size) ((1 << size) - 1)
  2850. #define DART_NATIVE_ARG_DESCRIPTOR(type, position) \
  2851. (((type & BITMASK(kNativeArgTypeSize)) << kNativeArgTypePos) | \
  2852. (position & BITMASK(kNativeArgNumberSize)))
  2853. /**
  2854. * Gets the native arguments based on the types passed in and populates
  2855. * the passed arguments buffer with appropriate native values.
  2856. *
  2857. * \param args the Native arguments block passed into the native call.
  2858. * \param num_arguments length of argument descriptor array and argument
  2859. * values array passed in.
  2860. * \param arg_descriptors an array that describes the arguments that
  2861. * need to be retrieved. For each argument to be retrieved the descriptor
  2862. * contains the argument number (0, 1 etc.) and the argument type
  2863. * described using Dart_NativeArgument_Type, e.g:
  2864. * DART_NATIVE_ARG_DESCRIPTOR(Dart_NativeArgument_kBool, 1) indicates
  2865. * that the first argument is to be retrieved and it should be a boolean.
  2866. * \param arg_values array into which the native arguments need to be
  2867. * extracted into, the array is allocated by the caller (it could be
  2868. * stack allocated to avoid the malloc/free performance overhead).
  2869. *
  2870. * \return Success if all the arguments could be extracted correctly,
  2871. * returns an error handle if there were any errors while extracting the
  2872. * arguments (mismatched number of arguments, incorrect types, etc.).
  2873. */
  2874. DART_EXPORT Dart_Handle
  2875. Dart_GetNativeArguments(Dart_NativeArguments args,
  2876. int num_arguments,
  2877. const Dart_NativeArgument_Descriptor* arg_descriptors,
  2878. Dart_NativeArgument_Value* arg_values);
  2879. /**
  2880. * Gets the native argument at some index.
  2881. */
  2882. DART_EXPORT Dart_Handle Dart_GetNativeArgument(Dart_NativeArguments args,
  2883. int index);
  2884. /* TODO(turnidge): Specify the behavior of an out-of-bounds access. */
  2885. /**
  2886. * Gets the number of native arguments.
  2887. */
  2888. DART_EXPORT int Dart_GetNativeArgumentCount(Dart_NativeArguments args);
  2889. /**
  2890. * Gets all the native fields of the native argument at some index.
  2891. * \param args Native arguments structure.
  2892. * \param arg_index Index of the desired argument in the structure above.
  2893. * \param num_fields size of the intptr_t array 'field_values' passed in.
  2894. * \param field_values intptr_t array in which native field values are returned.
  2895. * \return Success if the native fields where copied in successfully. Otherwise
  2896. * returns an error handle. On success the native field values are copied
  2897. * into the 'field_values' array, if the argument at 'arg_index' is a
  2898. * null object then 0 is copied as the native field values into the
  2899. * 'field_values' array.
  2900. */
  2901. DART_EXPORT Dart_Handle
  2902. Dart_GetNativeFieldsOfArgument(Dart_NativeArguments args,
  2903. int arg_index,
  2904. int num_fields,
  2905. intptr_t* field_values);
  2906. /**
  2907. * Gets the native field of the receiver.
  2908. */
  2909. DART_EXPORT Dart_Handle Dart_GetNativeReceiver(Dart_NativeArguments args,
  2910. intptr_t* value);
  2911. /**
  2912. * Gets a string native argument at some index.
  2913. * \param args Native arguments structure.
  2914. * \param arg_index Index of the desired argument in the structure above.
  2915. * \param peer Returns the peer pointer if the string argument has one.
  2916. * \return Success if the string argument has a peer, if it does not
  2917. * have a peer then the String object is returned. Otherwise returns
  2918. * an error handle (argument is not a String object).
  2919. */
  2920. DART_EXPORT Dart_Handle Dart_GetNativeStringArgument(Dart_NativeArguments args,
  2921. int arg_index,
  2922. void** peer);
  2923. /**
  2924. * Gets an integer native argument at some index.
  2925. * \param args Native arguments structure.
  2926. * \param index Index of the desired argument in the structure above.
  2927. * \param value Returns the integer value if the argument is an Integer.
  2928. * \return Success if no error occurs. Otherwise returns an error handle.
  2929. */
  2930. DART_EXPORT Dart_Handle Dart_GetNativeIntegerArgument(Dart_NativeArguments args,
  2931. int index,
  2932. int64_t* value);
  2933. /**
  2934. * Gets a boolean native argument at some index.
  2935. * \param args Native arguments structure.
  2936. * \param index Index of the desired argument in the structure above.
  2937. * \param value Returns the boolean value if the argument is a Boolean.
  2938. * \return Success if no error occurs. Otherwise returns an error handle.
  2939. */
  2940. DART_EXPORT Dart_Handle Dart_GetNativeBooleanArgument(Dart_NativeArguments args,
  2941. int index,
  2942. bool* value);
  2943. /**
  2944. * Gets a double native argument at some index.
  2945. * \param args Native arguments structure.
  2946. * \param index Index of the desired argument in the structure above.
  2947. * \param value Returns the double value if the argument is a double.
  2948. * \return Success if no error occurs. Otherwise returns an error handle.
  2949. */
  2950. DART_EXPORT Dart_Handle Dart_GetNativeDoubleArgument(Dart_NativeArguments args,
  2951. int index,
  2952. double* value);
  2953. /**
  2954. * Sets the return value for a native function.
  2955. *
  2956. * If retval is an Error handle, then error will be propagated once
  2957. * the native functions exits. See Dart_PropagateError for a
  2958. * discussion of how different types of errors are propagated.
  2959. */
  2960. DART_EXPORT void Dart_SetReturnValue(Dart_NativeArguments args,
  2961. Dart_Handle retval);
  2962. DART_EXPORT void Dart_SetWeakHandleReturnValue(Dart_NativeArguments args,
  2963. Dart_WeakPersistentHandle rval);
  2964. DART_EXPORT void Dart_SetBooleanReturnValue(Dart_NativeArguments args,
  2965. bool retval);
  2966. DART_EXPORT void Dart_SetIntegerReturnValue(Dart_NativeArguments args,
  2967. int64_t retval);
  2968. DART_EXPORT void Dart_SetDoubleReturnValue(Dart_NativeArguments args,
  2969. double retval);
  2970. /**
  2971. * A native function.
  2972. */
  2973. typedef void (*Dart_NativeFunction)(Dart_NativeArguments arguments);
  2974. /**
  2975. * Native entry resolution callback.
  2976. *
  2977. * For libraries and scripts which have native functions, the embedder
  2978. * can provide a native entry resolver. This callback is used to map a
  2979. * name/arity to a Dart_NativeFunction. If no function is found, the
  2980. * callback should return NULL.
  2981. *
  2982. * The parameters to the native resolver function are:
  2983. * \param name a Dart string which is the name of the native function.
  2984. * \param num_of_arguments is the number of arguments expected by the
  2985. * native function.
  2986. * \param auto_setup_scope is a boolean flag that can be set by the resolver
  2987. * to indicate if this function needs a Dart API scope (see Dart_EnterScope/
  2988. * Dart_ExitScope) to be setup automatically by the VM before calling into
  2989. * the native function. By default most native functions would require this
  2990. * to be true but some light weight native functions which do not call back
  2991. * into the VM through the Dart API may not require a Dart scope to be
  2992. * setup automatically.
  2993. *
  2994. * \return A valid Dart_NativeFunction which resolves to a native entry point
  2995. * for the native function.
  2996. *
  2997. * See Dart_SetNativeResolver.
  2998. */
  2999. typedef Dart_NativeFunction (*Dart_NativeEntryResolver)(Dart_Handle name,
  3000. int num_of_arguments,
  3001. bool* auto_setup_scope);
  3002. /* TODO(turnidge): Consider renaming to NativeFunctionResolver or
  3003. * NativeResolver. */
  3004. /**
  3005. * Native entry symbol lookup callback.
  3006. *
  3007. * For libraries and scripts which have native functions, the embedder
  3008. * can provide a callback for mapping a native entry to a symbol. This callback
  3009. * maps a native function entry PC to the native function name. If no native
  3010. * entry symbol can be found, the callback should return NULL.
  3011. *
  3012. * The parameters to the native reverse resolver function are:
  3013. * \param nf A Dart_NativeFunction.
  3014. *
  3015. * \return A const UTF-8 string containing the symbol name or NULL.
  3016. *
  3017. * See Dart_SetNativeResolver.
  3018. */
  3019. typedef const uint8_t* (*Dart_NativeEntrySymbol)(Dart_NativeFunction nf);
  3020. /**
  3021. * FFI Native C function pointer resolver callback.
  3022. *
  3023. * See Dart_SetFfiNativeResolver.
  3024. */
  3025. typedef void* (*Dart_FfiNativeResolver)(const char* name, uintptr_t args_n);
  3026. /*
  3027. * ===========
  3028. * Environment
  3029. * ===========
  3030. */
  3031. /**
  3032. * An environment lookup callback function.
  3033. *
  3034. * \param name The name of the value to lookup in the environment.
  3035. *
  3036. * \return A valid handle to a string if the name exists in the
  3037. * current environment or Dart_Null() if not.
  3038. */
  3039. typedef Dart_Handle (*Dart_EnvironmentCallback)(Dart_Handle name);
  3040. /**
  3041. * Sets the environment callback for the current isolate. This
  3042. * callback is used to lookup environment values by name in the
  3043. * current environment. This enables the embedder to supply values for
  3044. * the const constructors bool.fromEnvironment, int.fromEnvironment
  3045. * and String.fromEnvironment.
  3046. */
  3047. DART_EXPORT Dart_Handle
  3048. Dart_SetEnvironmentCallback(Dart_EnvironmentCallback callback);
  3049. /**
  3050. * Sets the callback used to resolve native functions for a library.
  3051. *
  3052. * \param library A library.
  3053. * \param resolver A native entry resolver.
  3054. *
  3055. * \return A valid handle if the native resolver was set successfully.
  3056. */
  3057. DART_EXPORT Dart_Handle
  3058. Dart_SetNativeResolver(Dart_Handle library,
  3059. Dart_NativeEntryResolver resolver,
  3060. Dart_NativeEntrySymbol symbol);
  3061. /* TODO(turnidge): Rename to Dart_LibrarySetNativeResolver? */
  3062. /**
  3063. * Returns the callback used to resolve native functions for a library.
  3064. *
  3065. * \param library A library.
  3066. * \param resolver a pointer to a Dart_NativeEntryResolver
  3067. *
  3068. * \return A valid handle if the library was found.
  3069. */
  3070. DART_EXPORT Dart_Handle
  3071. Dart_GetNativeResolver(Dart_Handle library, Dart_NativeEntryResolver* resolver);
  3072. /**
  3073. * Returns the callback used to resolve native function symbols for a library.
  3074. *
  3075. * \param library A library.
  3076. * \param resolver a pointer to a Dart_NativeEntrySymbol.
  3077. *
  3078. * \return A valid handle if the library was found.
  3079. */
  3080. DART_EXPORT Dart_Handle Dart_GetNativeSymbol(Dart_Handle library,
  3081. Dart_NativeEntrySymbol* resolver);
  3082. /**
  3083. * Sets the callback used to resolve FFI native functions for a library.
  3084. * The resolved functions are expected to be a C function pointer of the
  3085. * correct signature (as specified in the `@FfiNative<NFT>()` function
  3086. * annotation in Dart code).
  3087. *
  3088. * NOTE: This is an experimental feature and might change in the future.
  3089. *
  3090. * \param library A library.
  3091. * \param resolver A native function resolver.
  3092. *
  3093. * \return A valid handle if the native resolver was set successfully.
  3094. */
  3095. DART_EXPORT Dart_Handle
  3096. Dart_SetFfiNativeResolver(Dart_Handle library, Dart_FfiNativeResolver resolver);
  3097. /*
  3098. * =====================
  3099. * Scripts and Libraries
  3100. * =====================
  3101. */
  3102. typedef enum {
  3103. Dart_kCanonicalizeUrl = 0,
  3104. Dart_kImportTag,
  3105. Dart_kKernelTag,
  3106. } Dart_LibraryTag;
  3107. /**
  3108. * The library tag handler is a multi-purpose callback provided by the
  3109. * embedder to the Dart VM. The embedder implements the tag handler to
  3110. * provide the ability to load Dart scripts and imports.
  3111. *
  3112. * -- TAGS --
  3113. *
  3114. * Dart_kCanonicalizeUrl
  3115. *
  3116. * This tag indicates that the embedder should canonicalize 'url' with
  3117. * respect to 'library'. For most embedders, the
  3118. * Dart_DefaultCanonicalizeUrl function is a sufficient implementation
  3119. * of this tag. The return value should be a string holding the
  3120. * canonicalized url.
  3121. *
  3122. * Dart_kImportTag
  3123. *
  3124. * This tag is used to load a library from IsolateMirror.loadUri. The embedder
  3125. * should call Dart_LoadLibraryFromKernel to provide the library to the VM. The
  3126. * return value should be an error or library (the result from
  3127. * Dart_LoadLibraryFromKernel).
  3128. *
  3129. * Dart_kKernelTag
  3130. *
  3131. * This tag is used to load the intermediate file (kernel) generated by
  3132. * the Dart front end. This tag is typically used when a 'hot-reload'
  3133. * of an application is needed and the VM is 'use dart front end' mode.
  3134. * The dart front end typically compiles all the scripts, imports and part
  3135. * files into one intermediate file hence we don't use the source/import or
  3136. * script tags. The return value should be an error or a TypedData containing
  3137. * the kernel bytes.
  3138. *
  3139. */
  3140. typedef Dart_Handle (*Dart_LibraryTagHandler)(
  3141. Dart_LibraryTag tag,
  3142. Dart_Handle library_or_package_map_url,
  3143. Dart_Handle url);
  3144. /**
  3145. * Sets library tag handler for the current isolate. This handler is
  3146. * used to handle the various tags encountered while loading libraries
  3147. * or scripts in the isolate.
  3148. *
  3149. * \param handler Handler code to be used for handling the various tags
  3150. * encountered while loading libraries or scripts in the isolate.
  3151. *
  3152. * \return If no error occurs, the handler is set for the isolate.
  3153. * Otherwise an error handle is returned.
  3154. *
  3155. * TODO(turnidge): Document.
  3156. */
  3157. DART_EXPORT Dart_Handle
  3158. Dart_SetLibraryTagHandler(Dart_LibraryTagHandler handler);
  3159. /**
  3160. * Handles deferred loading requests. When this handler is invoked, it should
  3161. * eventually load the deferred loading unit with the given id and call
  3162. * Dart_DeferredLoadComplete or Dart_DeferredLoadCompleteError. It is
  3163. * recommended that the loading occur asynchronously, but it is permitted to
  3164. * call Dart_DeferredLoadComplete or Dart_DeferredLoadCompleteError before the
  3165. * handler returns.
  3166. *
  3167. * If an error is returned, it will be propagated through
  3168. * `prefix.loadLibrary()`. This is useful for synchronous
  3169. * implementations, which must propagate any unwind errors from
  3170. * Dart_DeferredLoadComplete or Dart_DeferredLoadComplete. Otherwise the handler
  3171. * should return a non-error such as `Dart_Null()`.
  3172. */
  3173. typedef Dart_Handle (*Dart_DeferredLoadHandler)(intptr_t loading_unit_id);
  3174. /**
  3175. * Sets the deferred load handler for the current isolate. This handler is
  3176. * used to handle loading deferred imports in an AppJIT or AppAOT program.
  3177. */
  3178. DART_EXPORT Dart_Handle
  3179. Dart_SetDeferredLoadHandler(Dart_DeferredLoadHandler handler);
  3180. /**
  3181. * Notifies the VM that a deferred load completed successfully. This function
  3182. * will eventually cause the corresponding `prefix.loadLibrary()` futures to
  3183. * complete.
  3184. *
  3185. * Requires the current isolate to be the same current isolate during the
  3186. * invocation of the Dart_DeferredLoadHandler.
  3187. */
  3188. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3189. Dart_DeferredLoadComplete(intptr_t loading_unit_id,
  3190. const uint8_t* snapshot_data,
  3191. const uint8_t* snapshot_instructions);
  3192. /**
  3193. * Notifies the VM that a deferred load failed. This function
  3194. * will eventually cause the corresponding `prefix.loadLibrary()` futures to
  3195. * complete with an error.
  3196. *
  3197. * If `transient` is true, future invocations of `prefix.loadLibrary()` will
  3198. * trigger new load requests. If false, futures invocation will complete with
  3199. * the same error.
  3200. *
  3201. * Requires the current isolate to be the same current isolate during the
  3202. * invocation of the Dart_DeferredLoadHandler.
  3203. */
  3204. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3205. Dart_DeferredLoadCompleteError(intptr_t loading_unit_id,
  3206. const char* error_message,
  3207. bool transient);
  3208. /**
  3209. * Canonicalizes a url with respect to some library.
  3210. *
  3211. * The url is resolved with respect to the library's url and some url
  3212. * normalizations are performed.
  3213. *
  3214. * This canonicalization function should be sufficient for most
  3215. * embedders to implement the Dart_kCanonicalizeUrl tag.
  3216. *
  3217. * \param base_url The base url relative to which the url is
  3218. * being resolved.
  3219. * \param url The url being resolved and canonicalized. This
  3220. * parameter is a string handle.
  3221. *
  3222. * \return If no error occurs, a String object is returned. Otherwise
  3223. * an error handle is returned.
  3224. */
  3225. DART_EXPORT Dart_Handle Dart_DefaultCanonicalizeUrl(Dart_Handle base_url,
  3226. Dart_Handle url);
  3227. /**
  3228. * Loads the root library for the current isolate.
  3229. *
  3230. * Requires there to be no current root library.
  3231. *
  3232. * \param kernel_buffer A buffer which contains a kernel binary (see
  3233. * pkg/kernel/binary.md). Must remain valid until isolate group shutdown.
  3234. * \param kernel_size Length of the passed in buffer.
  3235. *
  3236. * \return A handle to the root library, or an error.
  3237. */
  3238. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3239. Dart_LoadScriptFromKernel(const uint8_t* kernel_buffer, intptr_t kernel_size);
  3240. /**
  3241. * Gets the library for the root script for the current isolate.
  3242. *
  3243. * If the root script has not yet been set for the current isolate,
  3244. * this function returns Dart_Null(). This function never returns an
  3245. * error handle.
  3246. *
  3247. * \return Returns the root Library for the current isolate or Dart_Null().
  3248. */
  3249. DART_EXPORT Dart_Handle Dart_RootLibrary(void);
  3250. /**
  3251. * Sets the root library for the current isolate.
  3252. *
  3253. * \return Returns an error handle if `library` is not a library handle.
  3254. */
  3255. DART_EXPORT Dart_Handle Dart_SetRootLibrary(Dart_Handle library);
  3256. /**
  3257. * Lookup or instantiate a legacy type by name and type arguments from a
  3258. * Library.
  3259. *
  3260. * \param library The library containing the class or interface.
  3261. * \param class_name The class name for the type.
  3262. * \param number_of_type_arguments Number of type arguments.
  3263. * For non parametric types the number of type arguments would be 0.
  3264. * \param type_arguments Pointer to an array of type arguments.
  3265. * For non parametric types a NULL would be passed in for this argument.
  3266. *
  3267. * \return If no error occurs, the type is returned.
  3268. * Otherwise an error handle is returned.
  3269. */
  3270. DART_EXPORT Dart_Handle Dart_GetType(Dart_Handle library,
  3271. Dart_Handle class_name,
  3272. intptr_t number_of_type_arguments,
  3273. Dart_Handle* type_arguments);
  3274. /**
  3275. * Lookup or instantiate a nullable type by name and type arguments from
  3276. * Library.
  3277. *
  3278. * \param library The library containing the class or interface.
  3279. * \param class_name The class name for the type.
  3280. * \param number_of_type_arguments Number of type arguments.
  3281. * For non parametric types the number of type arguments would be 0.
  3282. * \param type_arguments Pointer to an array of type arguments.
  3283. * For non parametric types a NULL would be passed in for this argument.
  3284. *
  3285. * \return If no error occurs, the type is returned.
  3286. * Otherwise an error handle is returned.
  3287. */
  3288. DART_EXPORT Dart_Handle Dart_GetNullableType(Dart_Handle library,
  3289. Dart_Handle class_name,
  3290. intptr_t number_of_type_arguments,
  3291. Dart_Handle* type_arguments);
  3292. /**
  3293. * Lookup or instantiate a non-nullable type by name and type arguments from
  3294. * Library.
  3295. *
  3296. * \param library The library containing the class or interface.
  3297. * \param class_name The class name for the type.
  3298. * \param number_of_type_arguments Number of type arguments.
  3299. * For non parametric types the number of type arguments would be 0.
  3300. * \param type_arguments Pointer to an array of type arguments.
  3301. * For non parametric types a NULL would be passed in for this argument.
  3302. *
  3303. * \return If no error occurs, the type is returned.
  3304. * Otherwise an error handle is returned.
  3305. */
  3306. DART_EXPORT Dart_Handle
  3307. Dart_GetNonNullableType(Dart_Handle library,
  3308. Dart_Handle class_name,
  3309. intptr_t number_of_type_arguments,
  3310. Dart_Handle* type_arguments);
  3311. /**
  3312. * Creates a nullable version of the provided type.
  3313. *
  3314. * \param type The type to be converted to a nullable type.
  3315. *
  3316. * \return If no error occurs, a nullable type is returned.
  3317. * Otherwise an error handle is returned.
  3318. */
  3319. DART_EXPORT Dart_Handle Dart_TypeToNullableType(Dart_Handle type);
  3320. /**
  3321. * Creates a non-nullable version of the provided type.
  3322. *
  3323. * \param type The type to be converted to a non-nullable type.
  3324. *
  3325. * \return If no error occurs, a non-nullable type is returned.
  3326. * Otherwise an error handle is returned.
  3327. */
  3328. DART_EXPORT Dart_Handle Dart_TypeToNonNullableType(Dart_Handle type);
  3329. /**
  3330. * A type's nullability.
  3331. *
  3332. * \param type A Dart type.
  3333. * \param result An out parameter containing the result of the check. True if
  3334. * the type is of the specified nullability, false otherwise.
  3335. *
  3336. * \return Returns an error handle if type is not of type Type.
  3337. */
  3338. DART_EXPORT Dart_Handle Dart_IsNullableType(Dart_Handle type, bool* result);
  3339. DART_EXPORT Dart_Handle Dart_IsNonNullableType(Dart_Handle type, bool* result);
  3340. DART_EXPORT Dart_Handle Dart_IsLegacyType(Dart_Handle type, bool* result);
  3341. /**
  3342. * Lookup a class or interface by name from a Library.
  3343. *
  3344. * \param library The library containing the class or interface.
  3345. * \param class_name The name of the class or interface.
  3346. *
  3347. * \return If no error occurs, the class or interface is
  3348. * returned. Otherwise an error handle is returned.
  3349. */
  3350. DART_EXPORT Dart_Handle Dart_GetClass(Dart_Handle library,
  3351. Dart_Handle class_name);
  3352. /* TODO(asiva): The above method needs to be removed once all uses
  3353. * of it are removed from the embedder code. */
  3354. /**
  3355. * Returns an import path to a Library, such as "file:///test.dart" or
  3356. * "dart:core".
  3357. */
  3358. DART_EXPORT Dart_Handle Dart_LibraryUrl(Dart_Handle library);
  3359. /**
  3360. * Returns a URL from which a Library was loaded.
  3361. */
  3362. DART_EXPORT Dart_Handle Dart_LibraryResolvedUrl(Dart_Handle library);
  3363. /**
  3364. * \return An array of libraries.
  3365. */
  3366. DART_EXPORT Dart_Handle Dart_GetLoadedLibraries(void);
  3367. DART_EXPORT Dart_Handle Dart_LookupLibrary(Dart_Handle url);
  3368. /* TODO(turnidge): Consider returning Dart_Null() when the library is
  3369. * not found to distinguish that from a true error case. */
  3370. /**
  3371. * Report an loading error for the library.
  3372. *
  3373. * \param library The library that failed to load.
  3374. * \param error The Dart error instance containing the load error.
  3375. *
  3376. * \return If the VM handles the error, the return value is
  3377. * a null handle. If it doesn't handle the error, the error
  3378. * object is returned.
  3379. */
  3380. DART_EXPORT Dart_Handle Dart_LibraryHandleError(Dart_Handle library,
  3381. Dart_Handle error);
  3382. /**
  3383. * Called by the embedder to load a partial program. Does not set the root
  3384. * library.
  3385. *
  3386. * \param kernel_buffer A buffer which contains a kernel binary (see
  3387. * pkg/kernel/binary.md). Must remain valid until isolate shutdown.
  3388. * \param kernel_buffer_size Length of the passed in buffer.
  3389. *
  3390. * \return A handle to the main library of the compilation unit, or an error.
  3391. */
  3392. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3393. Dart_LoadLibraryFromKernel(const uint8_t* kernel_buffer,
  3394. intptr_t kernel_buffer_size);
  3395. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3396. Dart_LoadLibrary(Dart_Handle kernel_buffer);
  3397. /**
  3398. * Indicates that all outstanding load requests have been satisfied.
  3399. * This finalizes all the new classes loaded and optionally completes
  3400. * deferred library futures.
  3401. *
  3402. * Requires there to be a current isolate.
  3403. *
  3404. * \param complete_futures Specify true if all deferred library
  3405. * futures should be completed, false otherwise.
  3406. *
  3407. * \return Success if all classes have been finalized and deferred library
  3408. * futures are completed. Otherwise, returns an error.
  3409. */
  3410. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3411. Dart_FinalizeLoading(bool complete_futures);
  3412. /*
  3413. * =====
  3414. * Peers
  3415. * =====
  3416. */
  3417. /**
  3418. * The peer field is a lazily allocated field intended for storage of
  3419. * an uncommonly used values. Most instances types can have a peer
  3420. * field allocated. The exceptions are subtypes of Null, num, and
  3421. * bool.
  3422. */
  3423. /**
  3424. * Returns the value of peer field of 'object' in 'peer'.
  3425. *
  3426. * \param object An object.
  3427. * \param peer An out parameter that returns the value of the peer
  3428. * field.
  3429. *
  3430. * \return Returns an error if 'object' is a subtype of Null, num, or
  3431. * bool.
  3432. */
  3433. DART_EXPORT Dart_Handle Dart_GetPeer(Dart_Handle object, void** peer);
  3434. /**
  3435. * Sets the value of the peer field of 'object' to the value of
  3436. * 'peer'.
  3437. *
  3438. * \param object An object.
  3439. * \param peer A value to store in the peer field.
  3440. *
  3441. * \return Returns an error if 'object' is a subtype of Null, num, or
  3442. * bool.
  3443. */
  3444. DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer);
  3445. /*
  3446. * ======
  3447. * Kernel
  3448. * ======
  3449. */
  3450. /**
  3451. * Experimental support for Dart to Kernel parser isolate.
  3452. *
  3453. * TODO(hausner): Document finalized interface.
  3454. *
  3455. */
  3456. // TODO(33433): Remove kernel service from the embedding API.
  3457. typedef enum {
  3458. Dart_KernelCompilationStatus_Unknown = -1,
  3459. Dart_KernelCompilationStatus_Ok = 0,
  3460. Dart_KernelCompilationStatus_Error = 1,
  3461. Dart_KernelCompilationStatus_Crash = 2,
  3462. Dart_KernelCompilationStatus_MsgFailed = 3,
  3463. } Dart_KernelCompilationStatus;
  3464. typedef struct {
  3465. Dart_KernelCompilationStatus status;
  3466. bool null_safety;
  3467. char* error;
  3468. uint8_t* kernel;
  3469. intptr_t kernel_size;
  3470. } Dart_KernelCompilationResult;
  3471. typedef enum {
  3472. Dart_KernelCompilationVerbosityLevel_Error = 0,
  3473. Dart_KernelCompilationVerbosityLevel_Warning,
  3474. Dart_KernelCompilationVerbosityLevel_Info,
  3475. Dart_KernelCompilationVerbosityLevel_All,
  3476. } Dart_KernelCompilationVerbosityLevel;
  3477. DART_EXPORT bool Dart_IsKernelIsolate(Dart_Isolate isolate);
  3478. DART_EXPORT bool Dart_KernelIsolateIsRunning(void);
  3479. DART_EXPORT Dart_Port Dart_KernelPort(void);
  3480. /**
  3481. * Compiles the given `script_uri` to a kernel file.
  3482. *
  3483. * \param platform_kernel A buffer containing the kernel of the platform (e.g.
  3484. * `vm_platform_strong.dill`). The VM does not take ownership of this memory.
  3485. *
  3486. * \param platform_kernel_size The length of the platform_kernel buffer.
  3487. *
  3488. * \param snapshot_compile Set to `true` when the compilation is for a snapshot.
  3489. * This is used by the frontend to determine if compilation related information
  3490. * should be printed to console (e.g., null safety mode).
  3491. *
  3492. * \param verbosity Specifies the logging behavior of the kernel compilation
  3493. * service.
  3494. *
  3495. * \return Returns the result of the compilation.
  3496. *
  3497. * On a successful compilation the returned [Dart_KernelCompilationResult] has
  3498. * a status of [Dart_KernelCompilationStatus_Ok] and the `kernel`/`kernel_size`
  3499. * fields are set. The caller takes ownership of the malloc()ed buffer.
  3500. *
  3501. * On a failed compilation the `error` might be set describing the reason for
  3502. * the failed compilation. The caller takes ownership of the malloc()ed
  3503. * error.
  3504. *
  3505. * Requires there to be a current isolate.
  3506. */
  3507. DART_EXPORT Dart_KernelCompilationResult
  3508. Dart_CompileToKernel(const char* script_uri,
  3509. const uint8_t* platform_kernel,
  3510. const intptr_t platform_kernel_size,
  3511. bool incremental_compile,
  3512. bool snapshot_compile,
  3513. const char* package_config,
  3514. Dart_KernelCompilationVerbosityLevel verbosity);
  3515. typedef struct {
  3516. const char* uri;
  3517. const char* source;
  3518. } Dart_SourceFile;
  3519. DART_EXPORT Dart_KernelCompilationResult Dart_KernelListDependencies(void);
  3520. /**
  3521. * Sets the kernel buffer which will be used to load Dart SDK sources
  3522. * dynamically at runtime.
  3523. *
  3524. * \param platform_kernel A buffer containing kernel which has sources for the
  3525. * Dart SDK populated. Note: The VM does not take ownership of this memory.
  3526. *
  3527. * \param platform_kernel_size The length of the platform_kernel buffer.
  3528. */
  3529. DART_EXPORT void Dart_SetDartLibrarySourcesKernel(
  3530. const uint8_t* platform_kernel,
  3531. const intptr_t platform_kernel_size);
  3532. /**
  3533. * Detect the null safety opt-in status.
  3534. *
  3535. * When running from source, it is based on the opt-in status of `script_uri`.
  3536. * When running from a kernel buffer, it is based on the mode used when
  3537. * generating `kernel_buffer`.
  3538. * When running from an appJIT or AOT snapshot, it is based on the mode used
  3539. * when generating `snapshot_data`.
  3540. *
  3541. * \param script_uri Uri of the script that contains the source code
  3542. *
  3543. * \param package_config Uri of the package configuration file (either in format
  3544. * of .packages or .dart_tool/package_config.json) for the null safety
  3545. * detection to resolve package imports against. If this parameter is not
  3546. * passed the package resolution of the parent isolate should be used.
  3547. *
  3548. * \param original_working_directory current working directory when the VM
  3549. * process was launched, this is used to correctly resolve the path specified
  3550. * for package_config.
  3551. *
  3552. * \param snapshot_data Buffer containing the snapshot data of the
  3553. * isolate or NULL if no snapshot is provided. If provided, the buffers must
  3554. * remain valid until the isolate shuts down.
  3555. *
  3556. * \param snapshot_instructions Buffer containing the snapshot instructions of
  3557. * the isolate or NULL if no snapshot is provided. If provided, the buffers
  3558. * must remain valid until the isolate shuts down.
  3559. *
  3560. * \param kernel_buffer A buffer which contains a kernel/DIL program. Must
  3561. * remain valid until isolate shutdown.
  3562. *
  3563. * \param kernel_buffer_size The size of `kernel_buffer`.
  3564. *
  3565. * \return Returns true if the null safety is opted in by the input being
  3566. * run `script_uri`, `snapshot_data` or `kernel_buffer`.
  3567. *
  3568. */
  3569. DART_EXPORT bool Dart_DetectNullSafety(const char* script_uri,
  3570. const char* package_config,
  3571. const char* original_working_directory,
  3572. const uint8_t* snapshot_data,
  3573. const uint8_t* snapshot_instructions,
  3574. const uint8_t* kernel_buffer,
  3575. intptr_t kernel_buffer_size);
  3576. #define DART_KERNEL_ISOLATE_NAME "kernel-service"
  3577. /*
  3578. * =======
  3579. * Service
  3580. * =======
  3581. */
  3582. #define DART_VM_SERVICE_ISOLATE_NAME "vm-service"
  3583. /**
  3584. * Returns true if isolate is the service isolate.
  3585. *
  3586. * \param isolate An isolate
  3587. *
  3588. * \return Returns true if 'isolate' is the service isolate.
  3589. */
  3590. DART_EXPORT bool Dart_IsServiceIsolate(Dart_Isolate isolate);
  3591. /**
  3592. * Writes the CPU profile to the timeline as a series of 'instant' events.
  3593. *
  3594. * Note that this is an expensive operation.
  3595. *
  3596. * \param main_port The main port of the Isolate whose profile samples to write.
  3597. * \param error An optional error, must be free()ed by caller.
  3598. *
  3599. * \return Returns true if the profile is successfully written and false
  3600. * otherwise.
  3601. */
  3602. DART_EXPORT bool Dart_WriteProfileToTimeline(Dart_Port main_port, char** error);
  3603. /*
  3604. * ==============
  3605. * Precompilation
  3606. * ==============
  3607. */
  3608. /**
  3609. * Compiles all functions reachable from entry points and marks
  3610. * the isolate to disallow future compilation.
  3611. *
  3612. * Entry points should be specified using `@pragma("vm:entry-point")`
  3613. * annotation.
  3614. *
  3615. * \return An error handle if a compilation error or runtime error running const
  3616. * constructors was encountered.
  3617. */
  3618. DART_EXPORT Dart_Handle Dart_Precompile(void);
  3619. typedef void (*Dart_CreateLoadingUnitCallback)(
  3620. void* callback_data,
  3621. intptr_t loading_unit_id,
  3622. void** write_callback_data,
  3623. void** write_debug_callback_data);
  3624. typedef void (*Dart_StreamingWriteCallback)(void* callback_data,
  3625. const uint8_t* buffer,
  3626. intptr_t size);
  3627. typedef void (*Dart_StreamingCloseCallback)(void* callback_data);
  3628. DART_EXPORT Dart_Handle Dart_LoadingUnitLibraryUris(intptr_t loading_unit_id);
  3629. // On Darwin systems, 'dlsym' adds an '_' to the beginning of the symbol name.
  3630. // Use the '...CSymbol' definitions for resolving through 'dlsym'. The actual
  3631. // symbol names in the objects are given by the '...AsmSymbol' definitions.
  3632. #if defined(__APPLE__)
  3633. #define kSnapshotBuildIdCSymbol "kDartSnapshotBuildId"
  3634. #define kVmSnapshotDataCSymbol "kDartVmSnapshotData"
  3635. #define kVmSnapshotInstructionsCSymbol "kDartVmSnapshotInstructions"
  3636. #define kVmSnapshotBssCSymbol "kDartVmSnapshotBss"
  3637. #define kIsolateSnapshotDataCSymbol "kDartIsolateSnapshotData"
  3638. #define kIsolateSnapshotInstructionsCSymbol "kDartIsolateSnapshotInstructions"
  3639. #define kIsolateSnapshotBssCSymbol "kDartIsolateSnapshotBss"
  3640. #else
  3641. #define kSnapshotBuildIdCSymbol "_kDartSnapshotBuildId"
  3642. #define kVmSnapshotDataCSymbol "_kDartVmSnapshotData"
  3643. #define kVmSnapshotInstructionsCSymbol "_kDartVmSnapshotInstructions"
  3644. #define kVmSnapshotBssCSymbol "_kDartVmSnapshotBss"
  3645. #define kIsolateSnapshotDataCSymbol "_kDartIsolateSnapshotData"
  3646. #define kIsolateSnapshotInstructionsCSymbol "_kDartIsolateSnapshotInstructions"
  3647. #define kIsolateSnapshotBssCSymbol "_kDartIsolateSnapshotBss"
  3648. #endif
  3649. #define kSnapshotBuildIdAsmSymbol "_kDartSnapshotBuildId"
  3650. #define kVmSnapshotDataAsmSymbol "_kDartVmSnapshotData"
  3651. #define kVmSnapshotInstructionsAsmSymbol "_kDartVmSnapshotInstructions"
  3652. #define kVmSnapshotBssAsmSymbol "_kDartVmSnapshotBss"
  3653. #define kIsolateSnapshotDataAsmSymbol "_kDartIsolateSnapshotData"
  3654. #define kIsolateSnapshotInstructionsAsmSymbol \
  3655. "_kDartIsolateSnapshotInstructions"
  3656. #define kIsolateSnapshotBssAsmSymbol "_kDartIsolateSnapshotBss"
  3657. /**
  3658. * Creates a precompiled snapshot.
  3659. * - A root library must have been loaded.
  3660. * - Dart_Precompile must have been called.
  3661. *
  3662. * Outputs an assembly file defining the symbols listed in the definitions
  3663. * above.
  3664. *
  3665. * The assembly should be compiled as a static or shared library and linked or
  3666. * loaded by the embedder. Running this snapshot requires a VM compiled with
  3667. * DART_PRECOMPILED_SNAPSHOT. The kDartVmSnapshotData and
  3668. * kDartVmSnapshotInstructions should be passed to Dart_Initialize. The
  3669. * kDartIsolateSnapshotData and kDartIsolateSnapshotInstructions should be
  3670. * passed to Dart_CreateIsolateGroup.
  3671. *
  3672. * The callback will be invoked one or more times to provide the assembly code.
  3673. *
  3674. * If stripped is true, then the assembly code will not include DWARF
  3675. * debugging sections.
  3676. *
  3677. * If debug_callback_data is provided, debug_callback_data will be used with
  3678. * the callback to provide separate debugging information.
  3679. *
  3680. * \return A valid handle if no error occurs during the operation.
  3681. */
  3682. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3683. Dart_CreateAppAOTSnapshotAsAssembly(Dart_StreamingWriteCallback callback,
  3684. void* callback_data,
  3685. bool stripped,
  3686. void* debug_callback_data);
  3687. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3688. Dart_CreateAppAOTSnapshotAsAssemblies(
  3689. Dart_CreateLoadingUnitCallback next_callback,
  3690. void* next_callback_data,
  3691. bool stripped,
  3692. Dart_StreamingWriteCallback write_callback,
  3693. Dart_StreamingCloseCallback close_callback);
  3694. /**
  3695. * Creates a precompiled snapshot.
  3696. * - A root library must have been loaded.
  3697. * - Dart_Precompile must have been called.
  3698. *
  3699. * Outputs an ELF shared library defining the symbols
  3700. * - _kDartVmSnapshotData
  3701. * - _kDartVmSnapshotInstructions
  3702. * - _kDartIsolateSnapshotData
  3703. * - _kDartIsolateSnapshotInstructions
  3704. *
  3705. * The shared library should be dynamically loaded by the embedder.
  3706. * Running this snapshot requires a VM compiled with DART_PRECOMPILED_SNAPSHOT.
  3707. * The kDartVmSnapshotData and kDartVmSnapshotInstructions should be passed to
  3708. * Dart_Initialize. The kDartIsolateSnapshotData and
  3709. * kDartIsolateSnapshotInstructions should be passed to Dart_CreateIsolate.
  3710. *
  3711. * The callback will be invoked one or more times to provide the binary output.
  3712. *
  3713. * If stripped is true, then the binary output will not include DWARF
  3714. * debugging sections.
  3715. *
  3716. * If debug_callback_data is provided, debug_callback_data will be used with
  3717. * the callback to provide separate debugging information.
  3718. *
  3719. * \return A valid handle if no error occurs during the operation.
  3720. */
  3721. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3722. Dart_CreateAppAOTSnapshotAsElf(Dart_StreamingWriteCallback callback,
  3723. void* callback_data,
  3724. bool stripped,
  3725. void* debug_callback_data);
  3726. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3727. Dart_CreateAppAOTSnapshotAsElfs(Dart_CreateLoadingUnitCallback next_callback,
  3728. void* next_callback_data,
  3729. bool stripped,
  3730. Dart_StreamingWriteCallback write_callback,
  3731. Dart_StreamingCloseCallback close_callback);
  3732. /**
  3733. * Like Dart_CreateAppAOTSnapshotAsAssembly, but only includes
  3734. * kDartVmSnapshotData and kDartVmSnapshotInstructions. It also does
  3735. * not strip DWARF information from the generated assembly or allow for
  3736. * separate debug information.
  3737. */
  3738. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3739. Dart_CreateVMAOTSnapshotAsAssembly(Dart_StreamingWriteCallback callback,
  3740. void* callback_data);
  3741. /**
  3742. * Sorts the class-ids in depth first traversal order of the inheritance
  3743. * tree. This is a costly operation, but it can make method dispatch
  3744. * more efficient and is done before writing snapshots.
  3745. *
  3746. * \return A valid handle if no error occurs during the operation.
  3747. */
  3748. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_SortClasses(void);
  3749. /**
  3750. * Creates a snapshot that caches compiled code and type feedback for faster
  3751. * startup and quicker warmup in a subsequent process.
  3752. *
  3753. * Outputs a snapshot in two pieces. The pieces should be passed to
  3754. * Dart_CreateIsolateGroup in a VM using the same VM snapshot pieces used in the
  3755. * current VM. The instructions piece must be loaded with read and execute
  3756. * permissions; the data piece may be loaded as read-only.
  3757. *
  3758. * - Requires the VM to have not been started with --precompilation.
  3759. * - Not supported when targeting IA32.
  3760. * - The VM writing the snapshot and the VM reading the snapshot must be the
  3761. * same version, must be built in the same DEBUG/RELEASE/PRODUCT mode, must
  3762. * be targeting the same architecture, and must both be in checked mode or
  3763. * both in unchecked mode.
  3764. *
  3765. * The buffers are scope allocated and are only valid until the next call to
  3766. * Dart_ExitScope.
  3767. *
  3768. * \return A valid handle if no error occurs during the operation.
  3769. */
  3770. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3771. Dart_CreateAppJITSnapshotAsBlobs(uint8_t** isolate_snapshot_data_buffer,
  3772. intptr_t* isolate_snapshot_data_size,
  3773. uint8_t** isolate_snapshot_instructions_buffer,
  3774. intptr_t* isolate_snapshot_instructions_size);
  3775. /**
  3776. * Like Dart_CreateAppJITSnapshotAsBlobs, but also creates a new VM snapshot.
  3777. */
  3778. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3779. Dart_CreateCoreJITSnapshotAsBlobs(
  3780. uint8_t** vm_snapshot_data_buffer,
  3781. intptr_t* vm_snapshot_data_size,
  3782. uint8_t** vm_snapshot_instructions_buffer,
  3783. intptr_t* vm_snapshot_instructions_size,
  3784. uint8_t** isolate_snapshot_data_buffer,
  3785. intptr_t* isolate_snapshot_data_size,
  3786. uint8_t** isolate_snapshot_instructions_buffer,
  3787. intptr_t* isolate_snapshot_instructions_size);
  3788. /**
  3789. * Get obfuscation map for precompiled code.
  3790. *
  3791. * Obfuscation map is encoded as a JSON array of pairs (original name,
  3792. * obfuscated name).
  3793. *
  3794. * \return Returns an error handler if the VM was built in a mode that does not
  3795. * support obfuscation.
  3796. */
  3797. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
  3798. Dart_GetObfuscationMap(uint8_t** buffer, intptr_t* buffer_length);
  3799. /**
  3800. * Returns whether the VM only supports running from precompiled snapshots and
  3801. * not from any other kind of snapshot or from source (that is, the VM was
  3802. * compiled with DART_PRECOMPILED_RUNTIME).
  3803. */
  3804. DART_EXPORT bool Dart_IsPrecompiledRuntime(void);
  3805. /**
  3806. * Print a native stack trace. Used for crash handling.
  3807. *
  3808. * If context is NULL, prints the current stack trace. Otherwise, context
  3809. * should be a CONTEXT* (Windows) or ucontext_t* (POSIX) from a signal handler
  3810. * running on the current thread.
  3811. */
  3812. DART_EXPORT void Dart_DumpNativeStackTrace(void* context);
  3813. /**
  3814. * Indicate that the process is about to abort, and the Dart VM should not
  3815. * attempt to cleanup resources.
  3816. */
  3817. DART_EXPORT void Dart_PrepareToAbort(void);
  3818. /**
  3819. * Callback provided by the embedder that is used by the VM to
  3820. * produce footnotes appended to DWARF stack traces.
  3821. *
  3822. * Whenever VM formats a stack trace as a string it would call this callback
  3823. * passing raw program counters for each frame in the stack trace.
  3824. *
  3825. * Embedder can then return a string which if not-null will be appended to the
  3826. * formatted stack trace.
  3827. *
  3828. * Returned string is expected to be `malloc()` allocated. VM takes ownership
  3829. * of the returned string and will `free()` it.
  3830. *
  3831. * \param addresses raw program counter addresses for each frame
  3832. * \param count number of elements in the addresses array
  3833. */
  3834. typedef char* (*Dart_DwarfStackTraceFootnoteCallback)(void* addresses[],
  3835. intptr_t count);
  3836. /**
  3837. * Configure DWARF stack trace footnote callback.
  3838. */
  3839. DART_EXPORT void Dart_SetDwarfStackTraceFootnoteCallback(
  3840. Dart_DwarfStackTraceFootnoteCallback callback);
  3841. #endif /* INCLUDE_DART_API_H_ */ /* NOLINT */