123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185 |
- /*
- * Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file
- * for details. All rights reserved. Use of this source code is governed by a
- * BSD-style license that can be found in the LICENSE file.
- */
- #ifndef RUNTIME_INCLUDE_DART_API_H_
- #define RUNTIME_INCLUDE_DART_API_H_
- /** \mainpage Dart Embedding API Reference
- *
- * This reference describes the Dart Embedding API, which is used to embed the
- * Dart Virtual Machine within C/C++ applications.
- *
- * This reference is generated from the header include/dart_api.h.
- */
- /* __STDC_FORMAT_MACROS has to be defined before including <inttypes.h> to
- * enable platform independent printf format specifiers. */
- #ifndef __STDC_FORMAT_MACROS
- #define __STDC_FORMAT_MACROS
- #endif
- #include <assert.h>
- #include <inttypes.h>
- #include <stdbool.h>
- #if defined(__Fuchsia__)
- #include <zircon/types.h>
- #endif
- #ifdef __cplusplus
- #define DART_EXTERN_C extern "C"
- #else
- #define DART_EXTERN_C extern
- #endif
- #if defined(__CYGWIN__)
- #error Tool chain and platform not supported.
- #elif defined(_WIN32)
- #if defined(DART_SHARED_LIB)
- #define DART_EXPORT DART_EXTERN_C __declspec(dllexport)
- #else
- #define DART_EXPORT DART_EXTERN_C
- #endif
- #else
- #if __GNUC__ >= 4
- #if defined(DART_SHARED_LIB)
- #define DART_EXPORT \
- DART_EXTERN_C __attribute__((visibility("default"))) __attribute((used))
- #else
- #define DART_EXPORT DART_EXTERN_C
- #endif
- #else
- #error Tool chain not supported.
- #endif
- #endif
- #if __GNUC__
- #define DART_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
- #elif _MSC_VER
- #define DART_WARN_UNUSED_RESULT _Check_return_
- #else
- #define DART_WARN_UNUSED_RESULT
- #endif
- /*
- * =======
- * Handles
- * =======
- */
- /**
- * An isolate is the unit of concurrency in Dart. Each isolate has
- * its own memory and thread of control. No state is shared between
- * isolates. Instead, isolates communicate by message passing.
- *
- * Each thread keeps track of its current isolate, which is the
- * isolate which is ready to execute on the current thread. The
- * current isolate may be NULL, in which case no isolate is ready to
- * execute. Most of the Dart apis require there to be a current
- * isolate in order to function without error. The current isolate is
- * set by any call to Dart_CreateIsolateGroup or Dart_EnterIsolate.
- */
- typedef struct _Dart_Isolate* Dart_Isolate;
- typedef struct _Dart_IsolateGroup* Dart_IsolateGroup;
- /**
- * An object reference managed by the Dart VM garbage collector.
- *
- * Because the garbage collector may move objects, it is unsafe to
- * refer to objects directly. Instead, we refer to objects through
- * handles, which are known to the garbage collector and updated
- * automatically when the object is moved. Handles should be passed
- * by value (except in cases like out-parameters) and should never be
- * allocated on the heap.
- *
- * Most functions in the Dart Embedding API return a handle. When a
- * function completes normally, this will be a valid handle to an
- * object in the Dart VM heap. This handle may represent the result of
- * the operation or it may be a special valid handle used merely to
- * indicate successful completion. Note that a valid handle may in
- * some cases refer to the null object.
- *
- * --- Error handles ---
- *
- * When a function encounters a problem that prevents it from
- * completing normally, it returns an error handle (See Dart_IsError).
- * An error handle has an associated error message that gives more
- * details about the problem (See Dart_GetError).
- *
- * There are four kinds of error handles that can be produced,
- * depending on what goes wrong:
- *
- * - Api error handles are produced when an api function is misused.
- * This happens when a Dart embedding api function is called with
- * invalid arguments or in an invalid context.
- *
- * - Unhandled exception error handles are produced when, during the
- * execution of Dart code, an exception is thrown but not caught.
- * Prototypically this would occur during a call to Dart_Invoke, but
- * it can occur in any function which triggers the execution of Dart
- * code (for example, Dart_ToString).
- *
- * An unhandled exception error provides access to an exception and
- * stacktrace via the functions Dart_ErrorGetException and
- * Dart_ErrorGetStackTrace.
- *
- * - Compilation error handles are produced when, during the execution
- * of Dart code, a compile-time error occurs. As above, this can
- * occur in any function which triggers the execution of Dart code.
- *
- * - Fatal error handles are produced when the system wants to shut
- * down the current isolate.
- *
- * --- Propagating errors ---
- *
- * When an error handle is returned from the top level invocation of
- * Dart code in a program, the embedder must handle the error as they
- * see fit. Often, the embedder will print the error message produced
- * by Dart_Error and exit the program.
- *
- * When an error is returned while in the body of a native function,
- * it can be propagated up the call stack by calling
- * Dart_PropagateError, Dart_SetReturnValue, or Dart_ThrowException.
- * Errors should be propagated unless there is a specific reason not
- * to. If an error is not propagated then it is ignored. For
- * example, if an unhandled exception error is ignored, that
- * effectively "catches" the unhandled exception. Fatal errors must
- * always be propagated.
- *
- * When an error is propagated, any current scopes created by
- * Dart_EnterScope will be exited.
- *
- * Using Dart_SetReturnValue to propagate an exception is somewhat
- * more convenient than using Dart_PropagateError, and should be
- * preferred for reasons discussed below.
- *
- * Dart_PropagateError and Dart_ThrowException do not return. Instead
- * they transfer control non-locally using a setjmp-like mechanism.
- * This can be inconvenient if you have resources that you need to
- * clean up before propagating the error.
- *
- * When relying on Dart_PropagateError, we often return error handles
- * rather than propagating them from helper functions. Consider the
- * following contrived example:
- *
- * 1 Dart_Handle isLongStringHelper(Dart_Handle arg) {
- * 2 intptr_t* length = 0;
- * 3 result = Dart_StringLength(arg, &length);
- * 4 if (Dart_IsError(result)) {
- * 5 return result;
- * 6 }
- * 7 return Dart_NewBoolean(length > 100);
- * 8 }
- * 9
- * 10 void NativeFunction_isLongString(Dart_NativeArguments args) {
- * 11 Dart_EnterScope();
- * 12 AllocateMyResource();
- * 13 Dart_Handle arg = Dart_GetNativeArgument(args, 0);
- * 14 Dart_Handle result = isLongStringHelper(arg);
- * 15 if (Dart_IsError(result)) {
- * 16 FreeMyResource();
- * 17 Dart_PropagateError(result);
- * 18 abort(); // will not reach here
- * 19 }
- * 20 Dart_SetReturnValue(result);
- * 21 FreeMyResource();
- * 22 Dart_ExitScope();
- * 23 }
- *
- * In this example, we have a native function which calls a helper
- * function to do its work. On line 5, the helper function could call
- * Dart_PropagateError, but that would not give the native function a
- * chance to call FreeMyResource(), causing a leak. Instead, the
- * helper function returns the error handle to the caller, giving the
- * caller a chance to clean up before propagating the error handle.
- *
- * When an error is propagated by calling Dart_SetReturnValue, the
- * native function will be allowed to complete normally and then the
- * exception will be propagated only once the native call
- * returns. This can be convenient, as it allows the C code to clean
- * up normally.
- *
- * The example can be written more simply using Dart_SetReturnValue to
- * propagate the error.
- *
- * 1 Dart_Handle isLongStringHelper(Dart_Handle arg) {
- * 2 intptr_t* length = 0;
- * 3 result = Dart_StringLength(arg, &length);
- * 4 if (Dart_IsError(result)) {
- * 5 return result
- * 6 }
- * 7 return Dart_NewBoolean(length > 100);
- * 8 }
- * 9
- * 10 void NativeFunction_isLongString(Dart_NativeArguments args) {
- * 11 Dart_EnterScope();
- * 12 AllocateMyResource();
- * 13 Dart_Handle arg = Dart_GetNativeArgument(args, 0);
- * 14 Dart_SetReturnValue(isLongStringHelper(arg));
- * 15 FreeMyResource();
- * 16 Dart_ExitScope();
- * 17 }
- *
- * In this example, the call to Dart_SetReturnValue on line 14 will
- * either return the normal return value or the error (potentially
- * generated on line 3). The call to FreeMyResource on line 15 will
- * execute in either case.
- *
- * --- Local and persistent handles ---
- *
- * Local handles are allocated within the current scope (see
- * Dart_EnterScope) and go away when the current scope exits. Unless
- * otherwise indicated, callers should assume that all functions in
- * the Dart embedding api return local handles.
- *
- * Persistent handles are allocated within the current isolate. They
- * can be used to store objects across scopes. Persistent handles have
- * the lifetime of the current isolate unless they are explicitly
- * deallocated (see Dart_DeletePersistentHandle).
- * The type Dart_Handle represents a handle (both local and persistent).
- * The type Dart_PersistentHandle is a Dart_Handle and it is used to
- * document that a persistent handle is expected as a parameter to a call
- * or the return value from a call is a persistent handle.
- *
- * FinalizableHandles are persistent handles which are auto deleted when
- * the object is garbage collected. It is never safe to use these handles
- * unless you know the object is still reachable.
- *
- * WeakPersistentHandles are persistent handles which are automatically set
- * to point Dart_Null when the object is garbage collected. They are not auto
- * deleted, so it is safe to use them after the object has become unreachable.
- */
- typedef struct _Dart_Handle* Dart_Handle;
- typedef Dart_Handle Dart_PersistentHandle;
- typedef struct _Dart_WeakPersistentHandle* Dart_WeakPersistentHandle;
- typedef struct _Dart_FinalizableHandle* Dart_FinalizableHandle;
- // These structs are versioned by DART_API_DL_MAJOR_VERSION, bump the
- // version when changing this struct.
- typedef void (*Dart_HandleFinalizer)(void* isolate_callback_data, void* peer);
- /**
- * Is this an error handle?
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT bool Dart_IsError(Dart_Handle handle);
- /**
- * Is this an api error handle?
- *
- * Api error handles are produced when an api function is misused.
- * This happens when a Dart embedding api function is called with
- * invalid arguments or in an invalid context.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT bool Dart_IsApiError(Dart_Handle handle);
- /**
- * Is this an unhandled exception error handle?
- *
- * Unhandled exception error handles are produced when, during the
- * execution of Dart code, an exception is thrown but not caught.
- * This can occur in any function which triggers the execution of Dart
- * code.
- *
- * See Dart_ErrorGetException and Dart_ErrorGetStackTrace.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT bool Dart_IsUnhandledExceptionError(Dart_Handle handle);
- /**
- * Is this a compilation error handle?
- *
- * Compilation error handles are produced when, during the execution
- * of Dart code, a compile-time error occurs. This can occur in any
- * function which triggers the execution of Dart code.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT bool Dart_IsCompilationError(Dart_Handle handle);
- /**
- * Is this a fatal error handle?
- *
- * Fatal error handles are produced when the system wants to shut down
- * the current isolate.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT bool Dart_IsFatalError(Dart_Handle handle);
- /**
- * Gets the error message from an error handle.
- *
- * Requires there to be a current isolate.
- *
- * \return A C string containing an error message if the handle is
- * error. An empty C string ("") if the handle is valid. This C
- * String is scope allocated and is only valid until the next call
- * to Dart_ExitScope.
- */
- DART_EXPORT const char* Dart_GetError(Dart_Handle handle);
- /**
- * Is this an error handle for an unhandled exception?
- */
- DART_EXPORT bool Dart_ErrorHasException(Dart_Handle handle);
- /**
- * Gets the exception Object from an unhandled exception error handle.
- */
- DART_EXPORT Dart_Handle Dart_ErrorGetException(Dart_Handle handle);
- /**
- * Gets the stack trace Object from an unhandled exception error handle.
- */
- DART_EXPORT Dart_Handle Dart_ErrorGetStackTrace(Dart_Handle handle);
- /**
- * Produces an api error handle with the provided error message.
- *
- * Requires there to be a current isolate.
- *
- * \param error the error message.
- */
- DART_EXPORT Dart_Handle Dart_NewApiError(const char* error);
- DART_EXPORT Dart_Handle Dart_NewCompilationError(const char* error);
- /**
- * Produces a new unhandled exception error handle.
- *
- * Requires there to be a current isolate.
- *
- * \param exception An instance of a Dart object to be thrown or
- * an ApiError or CompilationError handle.
- * When an ApiError or CompilationError handle is passed in
- * a string object of the error message is created and it becomes
- * the Dart object to be thrown.
- */
- DART_EXPORT Dart_Handle Dart_NewUnhandledExceptionError(Dart_Handle exception);
- /**
- * Propagates an error.
- *
- * If the provided handle is an unhandled exception error, this
- * function will cause the unhandled exception to be rethrown. This
- * will proceed in the standard way, walking up Dart frames until an
- * appropriate 'catch' block is found, executing 'finally' blocks,
- * etc.
- *
- * If the error is not an unhandled exception error, we will unwind
- * the stack to the next C frame. Intervening Dart frames will be
- * discarded; specifically, 'finally' blocks will not execute. This
- * is the standard way that compilation errors (and the like) are
- * handled by the Dart runtime.
- *
- * In either case, when an error is propagated any current scopes
- * created by Dart_EnterScope will be exited.
- *
- * See the additional discussion under "Propagating Errors" at the
- * beginning of this file.
- *
- * \param handle An error handle (See Dart_IsError)
- *
- * On success, this function does not return. On failure, the
- * process is terminated.
- */
- DART_EXPORT void Dart_PropagateError(Dart_Handle handle);
- /**
- * Converts an object to a string.
- *
- * May generate an unhandled exception error.
- *
- * \return The converted string if no error occurs during
- * the conversion. If an error does occur, an error handle is
- * returned.
- */
- DART_EXPORT Dart_Handle Dart_ToString(Dart_Handle object);
- /**
- * Checks to see if two handles refer to identically equal objects.
- *
- * If both handles refer to instances, this is equivalent to using the top-level
- * function identical() from dart:core. Otherwise, returns whether the two
- * argument handles refer to the same object.
- *
- * \param obj1 An object to be compared.
- * \param obj2 An object to be compared.
- *
- * \return True if the objects are identically equal. False otherwise.
- */
- DART_EXPORT bool Dart_IdentityEquals(Dart_Handle obj1, Dart_Handle obj2);
- /**
- * Allocates a handle in the current scope from a persistent handle.
- */
- DART_EXPORT Dart_Handle Dart_HandleFromPersistent(Dart_PersistentHandle object);
- /**
- * Allocates a handle in the current scope from a weak persistent handle.
- *
- * This will be a handle to Dart_Null if the object has been garbage collected.
- */
- DART_EXPORT Dart_Handle
- Dart_HandleFromWeakPersistent(Dart_WeakPersistentHandle object);
- /**
- * Allocates a persistent handle for an object.
- *
- * This handle has the lifetime of the current isolate unless it is
- * explicitly deallocated by calling Dart_DeletePersistentHandle.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT Dart_PersistentHandle Dart_NewPersistentHandle(Dart_Handle object);
- /**
- * Assign value of local handle to a persistent handle.
- *
- * Requires there to be a current isolate.
- *
- * \param obj1 A persistent handle whose value needs to be set.
- * \param obj2 An object whose value needs to be set to the persistent handle.
- */
- DART_EXPORT void Dart_SetPersistentHandle(Dart_PersistentHandle obj1,
- Dart_Handle obj2);
- /**
- * Deallocates a persistent handle.
- *
- * Requires there to be a current isolate group.
- */
- DART_EXPORT void Dart_DeletePersistentHandle(Dart_PersistentHandle object);
- /**
- * Allocates a weak persistent handle for an object.
- *
- * This handle has the lifetime of the current isolate. The handle can also be
- * explicitly deallocated by calling Dart_DeleteWeakPersistentHandle.
- *
- * If the object becomes unreachable the callback is invoked with the peer as
- * argument. The callback can be executed on any thread, will have a current
- * isolate group, but will not have a current isolate. The callback can only
- * call Dart_DeletePersistentHandle or Dart_DeleteWeakPersistentHandle. This
- * gives the embedder the ability to cleanup data associated with the object.
- * The handle will point to the Dart_Null object after the finalizer has been
- * run. It is illegal to call into the VM with any other Dart_* functions from
- * the callback. If the handle is deleted before the object becomes
- * unreachable, the callback is never invoked.
- *
- * Requires there to be a current isolate.
- *
- * \param object An object with identity.
- * \param peer A pointer to a native object or NULL. This value is
- * provided to callback when it is invoked.
- * \param external_allocation_size The number of externally allocated
- * bytes for peer. Used to inform the garbage collector.
- * \param callback A function pointer that will be invoked sometime
- * after the object is garbage collected, unless the handle has been deleted.
- * A valid callback needs to be specified it cannot be NULL.
- *
- * \return The weak persistent handle or NULL. NULL is returned in case of bad
- * parameters.
- */
- DART_EXPORT Dart_WeakPersistentHandle
- Dart_NewWeakPersistentHandle(Dart_Handle object,
- void* peer,
- intptr_t external_allocation_size,
- Dart_HandleFinalizer callback);
- /**
- * Deletes the given weak persistent [object] handle.
- *
- * Requires there to be a current isolate group.
- */
- DART_EXPORT void Dart_DeleteWeakPersistentHandle(
- Dart_WeakPersistentHandle object);
- /**
- * Updates the external memory size for the given weak persistent handle.
- *
- * May trigger garbage collection.
- */
- DART_EXPORT void Dart_UpdateExternalSize(Dart_WeakPersistentHandle object,
- intptr_t external_allocation_size);
- /**
- * Allocates a finalizable handle for an object.
- *
- * This handle has the lifetime of the current isolate group unless the object
- * pointed to by the handle is garbage collected, in this case the VM
- * automatically deletes the handle after invoking the callback associated
- * with the handle. The handle can also be explicitly deallocated by
- * calling Dart_DeleteFinalizableHandle.
- *
- * If the object becomes unreachable the callback is invoked with the
- * the peer as argument. The callback can be executed on any thread, will have
- * an isolate group, but will not have a current isolate. The callback can only
- * call Dart_DeletePersistentHandle or Dart_DeleteWeakPersistentHandle.
- * This gives the embedder the ability to cleanup data associated with the
- * object and clear out any cached references to the handle. All references to
- * this handle after the callback will be invalid. It is illegal to call into
- * the VM with any other Dart_* functions from the callback. If the handle is
- * deleted before the object becomes unreachable, the callback is never
- * invoked.
- *
- * Requires there to be a current isolate.
- *
- * \param object An object with identity.
- * \param peer A pointer to a native object or NULL. This value is
- * provided to callback when it is invoked.
- * \param external_allocation_size The number of externally allocated
- * bytes for peer. Used to inform the garbage collector.
- * \param callback A function pointer that will be invoked sometime
- * after the object is garbage collected, unless the handle has been deleted.
- * A valid callback needs to be specified it cannot be NULL.
- *
- * \return The finalizable handle or NULL. NULL is returned in case of bad
- * parameters.
- */
- DART_EXPORT Dart_FinalizableHandle
- Dart_NewFinalizableHandle(Dart_Handle object,
- void* peer,
- intptr_t external_allocation_size,
- Dart_HandleFinalizer callback);
- /**
- * Deletes the given finalizable [object] handle.
- *
- * The caller has to provide the actual Dart object the handle was created from
- * to prove the object (and therefore the finalizable handle) is still alive.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT void Dart_DeleteFinalizableHandle(Dart_FinalizableHandle object,
- Dart_Handle strong_ref_to_object);
- /**
- * Updates the external memory size for the given finalizable handle.
- *
- * The caller has to provide the actual Dart object the handle was created from
- * to prove the object (and therefore the finalizable handle) is still alive.
- *
- * May trigger garbage collection.
- */
- DART_EXPORT void Dart_UpdateFinalizableExternalSize(
- Dart_FinalizableHandle object,
- Dart_Handle strong_ref_to_object,
- intptr_t external_allocation_size);
- /*
- * ==========================
- * Initialization and Globals
- * ==========================
- */
- /**
- * Gets the version string for the Dart VM.
- *
- * The version of the Dart VM can be accessed without initializing the VM.
- *
- * \return The version string for the embedded Dart VM.
- */
- DART_EXPORT const char* Dart_VersionString(void);
- /**
- * Isolate specific flags are set when creating a new isolate using the
- * Dart_IsolateFlags structure.
- *
- * Current version of flags is encoded in a 32-bit integer with 16 bits used
- * for each part.
- */
- #define DART_FLAGS_CURRENT_VERSION (0x0000000c)
- typedef struct {
- int32_t version;
- bool enable_asserts;
- bool use_field_guards;
- bool use_osr;
- bool obfuscate;
- bool load_vmservice_library;
- bool copy_parent_code;
- bool null_safety;
- bool is_system_isolate;
- bool snapshot_is_dontneed_safe;
- bool branch_coverage;
- } Dart_IsolateFlags;
- /**
- * Initialize Dart_IsolateFlags with correct version and default values.
- */
- DART_EXPORT void Dart_IsolateFlagsInitialize(Dart_IsolateFlags* flags);
- /**
- * An isolate creation and initialization callback function.
- *
- * This callback, provided by the embedder, is called when the VM
- * needs to create an isolate. The callback should create an isolate
- * by calling Dart_CreateIsolateGroup and load any scripts required for
- * execution.
- *
- * This callback may be called on a different thread than the one
- * running the parent isolate.
- *
- * When the function returns NULL, it is the responsibility of this
- * function to ensure that Dart_ShutdownIsolate has been called if
- * required (for example, if the isolate was created successfully by
- * Dart_CreateIsolateGroup() but the root library fails to load
- * successfully, then the function should call Dart_ShutdownIsolate
- * before returning).
- *
- * When the function returns NULL, the function should set *error to
- * a malloc-allocated buffer containing a useful error message. The
- * caller of this function (the VM) will make sure that the buffer is
- * freed.
- *
- * \param script_uri The uri of the main source file or snapshot to load.
- * Either the URI of the parent isolate set in Dart_CreateIsolateGroup for
- * Isolate.spawn, or the argument to Isolate.spawnUri canonicalized by the
- * library tag handler of the parent isolate.
- * The callback is responsible for loading the program by a call to
- * Dart_LoadScriptFromKernel.
- * \param main The name of the main entry point this isolate will
- * eventually run. This is provided for advisory purposes only to
- * improve debugging messages. The main function is not invoked by
- * this function.
- * \param package_root Ignored.
- * \param package_config Uri of the package configuration file (either in format
- * of .packages or .dart_tool/package_config.json) for this isolate
- * to resolve package imports against. If this parameter is not passed the
- * package resolution of the parent isolate should be used.
- * \param flags Default flags for this isolate being spawned. Either inherited
- * from the spawning isolate or passed as parameters when spawning the
- * isolate from Dart code.
- * \param isolate_data The isolate data which was passed to the
- * parent isolate when it was created by calling Dart_CreateIsolateGroup().
- * \param error A structure into which the embedder can place a
- * C string containing an error message in the case of failures.
- *
- * \return The embedder returns NULL if the creation and
- * initialization was not successful and the isolate if successful.
- */
- typedef Dart_Isolate (*Dart_IsolateGroupCreateCallback)(
- const char* script_uri,
- const char* main,
- const char* package_root,
- const char* package_config,
- Dart_IsolateFlags* flags,
- void* isolate_data,
- char** error);
- /**
- * An isolate initialization callback function.
- *
- * This callback, provided by the embedder, is called when the VM has created an
- * isolate within an existing isolate group (i.e. from the same source as an
- * existing isolate).
- *
- * The callback should setup native resolvers and might want to set a custom
- * message handler via [Dart_SetMessageNotifyCallback] and mark the isolate as
- * runnable.
- *
- * This callback may be called on a different thread than the one
- * running the parent isolate.
- *
- * When the function returns `false`, it is the responsibility of this
- * function to ensure that `Dart_ShutdownIsolate` has been called.
- *
- * When the function returns `false`, the function should set *error to
- * a malloc-allocated buffer containing a useful error message. The
- * caller of this function (the VM) will make sure that the buffer is
- * freed.
- *
- * \param child_isolate_data The callback data to associate with the new
- * child isolate.
- * \param error A structure into which the embedder can place a
- * C string containing an error message in the case the initialization fails.
- *
- * \return The embedder returns true if the initialization was successful and
- * false otherwise (in which case the VM will terminate the isolate).
- */
- typedef bool (*Dart_InitializeIsolateCallback)(void** child_isolate_data,
- char** error);
- /**
- * An isolate shutdown callback function.
- *
- * This callback, provided by the embedder, is called before the vm
- * shuts down an isolate. The isolate being shutdown will be the current
- * isolate. It is safe to run Dart code.
- *
- * This function should be used to dispose of native resources that
- * are allocated to an isolate in order to avoid leaks.
- *
- * \param isolate_group_data The same callback data which was passed to the
- * isolate group when it was created.
- * \param isolate_data The same callback data which was passed to the isolate
- * when it was created.
- */
- typedef void (*Dart_IsolateShutdownCallback)(void* isolate_group_data,
- void* isolate_data);
- /**
- * An isolate cleanup callback function.
- *
- * This callback, provided by the embedder, is called after the vm
- * shuts down an isolate. There will be no current isolate and it is *not*
- * safe to run Dart code.
- *
- * This function should be used to dispose of native resources that
- * are allocated to an isolate in order to avoid leaks.
- *
- * \param isolate_group_data The same callback data which was passed to the
- * isolate group when it was created.
- * \param isolate_data The same callback data which was passed to the isolate
- * when it was created.
- */
- typedef void (*Dart_IsolateCleanupCallback)(void* isolate_group_data,
- void* isolate_data);
- /**
- * An isolate group cleanup callback function.
- *
- * This callback, provided by the embedder, is called after the vm
- * shuts down an isolate group.
- *
- * This function should be used to dispose of native resources that
- * are allocated to an isolate in order to avoid leaks.
- *
- * \param isolate_group_data The same callback data which was passed to the
- * isolate group when it was created.
- *
- */
- typedef void (*Dart_IsolateGroupCleanupCallback)(void* isolate_group_data);
- /**
- * A thread start callback function.
- * This callback, provided by the embedder, is called after a thread in the
- * vm thread pool starts.
- * This function could be used to adjust thread priority or attach native
- * resources to the thread.
- */
- typedef void (*Dart_ThreadStartCallback)(void);
- /**
- * A thread death callback function.
- * This callback, provided by the embedder, is called before a thread in the
- * vm thread pool exits.
- * This function could be used to dispose of native resources that
- * are associated and attached to the thread, in order to avoid leaks.
- */
- typedef void (*Dart_ThreadExitCallback)(void);
- /**
- * Opens a file for reading or writing.
- *
- * Callback provided by the embedder for file operations. If the
- * embedder does not allow file operations this callback can be
- * NULL.
- *
- * \param name The name of the file to open.
- * \param write A boolean variable which indicates if the file is to
- * opened for writing. If there is an existing file it needs to truncated.
- */
- typedef void* (*Dart_FileOpenCallback)(const char* name, bool write);
- /**
- * Read contents of file.
- *
- * Callback provided by the embedder for file operations. If the
- * embedder does not allow file operations this callback can be
- * NULL.
- *
- * \param data Buffer allocated in the callback into which the contents
- * of the file are read into. It is the responsibility of the caller to
- * free this buffer.
- * \param file_length A variable into which the length of the file is returned.
- * In the case of an error this value would be -1.
- * \param stream Handle to the opened file.
- */
- typedef void (*Dart_FileReadCallback)(uint8_t** data,
- intptr_t* file_length,
- void* stream);
- /**
- * Write data into file.
- *
- * Callback provided by the embedder for file operations. If the
- * embedder does not allow file operations this callback can be
- * NULL.
- *
- * \param data Buffer which needs to be written into the file.
- * \param length Length of the buffer.
- * \param stream Handle to the opened file.
- */
- typedef void (*Dart_FileWriteCallback)(const void* data,
- intptr_t length,
- void* stream);
- /**
- * Closes the opened file.
- *
- * Callback provided by the embedder for file operations. If the
- * embedder does not allow file operations this callback can be
- * NULL.
- *
- * \param stream Handle to the opened file.
- */
- typedef void (*Dart_FileCloseCallback)(void* stream);
- typedef bool (*Dart_EntropySource)(uint8_t* buffer, intptr_t length);
- /**
- * Callback provided by the embedder that is used by the vmservice isolate
- * to request the asset archive. The asset archive must be an uncompressed tar
- * archive that is stored in a Uint8List.
- *
- * If the embedder has no vmservice isolate assets, the callback can be NULL.
- *
- * \return The embedder must return a handle to a Uint8List containing an
- * uncompressed tar archive or null.
- */
- typedef Dart_Handle (*Dart_GetVMServiceAssetsArchive)(void);
- /**
- * The current version of the Dart_InitializeFlags. Should be incremented every
- * time Dart_InitializeFlags changes in a binary incompatible way.
- */
- #define DART_INITIALIZE_PARAMS_CURRENT_VERSION (0x00000008)
- /** Forward declaration */
- struct Dart_CodeObserver;
- /**
- * Callback provided by the embedder that is used by the VM to notify on code
- * object creation, *before* it is invoked the first time.
- * This is useful for embedders wanting to e.g. keep track of PCs beyond
- * the lifetime of the garbage collected code objects.
- * Note that an address range may be used by more than one code object over the
- * lifecycle of a process. Clients of this function should record timestamps for
- * these compilation events and when collecting PCs to disambiguate reused
- * address ranges.
- */
- typedef void (*Dart_OnNewCodeCallback)(struct Dart_CodeObserver* observer,
- const char* name,
- uintptr_t base,
- uintptr_t size);
- typedef struct Dart_CodeObserver {
- void* data;
- Dart_OnNewCodeCallback on_new_code;
- } Dart_CodeObserver;
- /**
- * Optional callback provided by the embedder that is used by the VM to
- * implement registration of kernel blobs for the subsequent Isolate.spawnUri
- * If no callback is provided, the registration of kernel blobs will throw
- * an error.
- *
- * \param kernel_buffer A buffer which contains a kernel program. Callback
- * should copy the contents of `kernel_buffer` as
- * it may be freed immediately after registration.
- * \param kernel_buffer_size The size of `kernel_buffer`.
- *
- * \return A C string representing URI which can be later used
- * to spawn a new isolate. This C String should be scope allocated
- * or owned by the embedder.
- * Returns NULL if embedder runs out of memory.
- */
- typedef const char* (*Dart_RegisterKernelBlobCallback)(
- const uint8_t* kernel_buffer,
- intptr_t kernel_buffer_size);
- /**
- * Optional callback provided by the embedder that is used by the VM to
- * unregister kernel blobs.
- * If no callback is provided, the unregistration of kernel blobs will throw
- * an error.
- *
- * \param kernel_blob_uri URI of the kernel blob to unregister.
- */
- typedef void (*Dart_UnregisterKernelBlobCallback)(const char* kernel_blob_uri);
- /**
- * Describes how to initialize the VM. Used with Dart_Initialize.
- */
- typedef struct {
- /**
- * Identifies the version of the struct used by the client.
- * should be initialized to DART_INITIALIZE_PARAMS_CURRENT_VERSION.
- */
- int32_t version;
- /**
- * A buffer containing snapshot data, or NULL if no snapshot is provided.
- *
- * If provided, the buffer must remain valid until Dart_Cleanup returns.
- */
- const uint8_t* vm_snapshot_data;
- /**
- * A buffer containing a snapshot of precompiled instructions, or NULL if
- * no snapshot is provided.
- *
- * If provided, the buffer must remain valid until Dart_Cleanup returns.
- */
- const uint8_t* vm_snapshot_instructions;
- /**
- * A function to be called during isolate group creation.
- * See Dart_IsolateGroupCreateCallback.
- */
- Dart_IsolateGroupCreateCallback create_group;
- /**
- * A function to be called during isolate
- * initialization inside an existing isolate group.
- * See Dart_InitializeIsolateCallback.
- */
- Dart_InitializeIsolateCallback initialize_isolate;
- /**
- * A function to be called right before an isolate is shutdown.
- * See Dart_IsolateShutdownCallback.
- */
- Dart_IsolateShutdownCallback shutdown_isolate;
- /**
- * A function to be called after an isolate was shutdown.
- * See Dart_IsolateCleanupCallback.
- */
- Dart_IsolateCleanupCallback cleanup_isolate;
- /**
- * A function to be called after an isolate group is
- * shutdown. See Dart_IsolateGroupCleanupCallback.
- */
- Dart_IsolateGroupCleanupCallback cleanup_group;
- Dart_ThreadStartCallback thread_start;
- Dart_ThreadExitCallback thread_exit;
- Dart_FileOpenCallback file_open;
- Dart_FileReadCallback file_read;
- Dart_FileWriteCallback file_write;
- Dart_FileCloseCallback file_close;
- Dart_EntropySource entropy_source;
- /**
- * A function to be called by the service isolate when it requires the
- * vmservice assets archive. See Dart_GetVMServiceAssetsArchive.
- */
- Dart_GetVMServiceAssetsArchive get_service_assets;
- bool start_kernel_isolate;
- /**
- * An external code observer callback function. The observer can be invoked
- * as early as during the Dart_Initialize() call.
- */
- Dart_CodeObserver* code_observer;
- /**
- * Kernel blob registration callback function. See Dart_RegisterKernelBlobCallback.
- */
- Dart_RegisterKernelBlobCallback register_kernel_blob;
- /**
- * Kernel blob unregistration callback function. See Dart_UnregisterKernelBlobCallback.
- */
- Dart_UnregisterKernelBlobCallback unregister_kernel_blob;
- #if defined(__Fuchsia__)
- /**
- * The resource needed to use zx_vmo_replace_as_executable. Can be
- * ZX_HANDLE_INVALID if the process has ambient-replace-as-executable or if
- * executable memory is not needed (e.g., this is an AOT runtime).
- */
- zx_handle_t vmex_resource;
- #endif
- } Dart_InitializeParams;
- /**
- * Initializes the VM.
- *
- * \param params A struct containing initialization information. The version
- * field of the struct must be DART_INITIALIZE_PARAMS_CURRENT_VERSION.
- *
- * \return NULL if initialization is successful. Returns an error message
- * otherwise. The caller is responsible for freeing the error message.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT char* Dart_Initialize(
- Dart_InitializeParams* params);
- /**
- * Cleanup state in the VM before process termination.
- *
- * \return NULL if cleanup is successful. Returns an error message otherwise.
- * The caller is responsible for freeing the error message.
- *
- * NOTE: This function must not be called on a thread that was created by the VM
- * itself.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT char* Dart_Cleanup(void);
- /**
- * Sets command line flags. Should be called before Dart_Initialize.
- *
- * \param argc The length of the arguments array.
- * \param argv An array of arguments.
- *
- * \return NULL if successful. Returns an error message otherwise.
- * The caller is responsible for freeing the error message.
- *
- * NOTE: This call does not store references to the passed in c-strings.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT char* Dart_SetVMFlags(int argc,
- const char** argv);
- /**
- * Returns true if the named VM flag is of boolean type, specified, and set to
- * true.
- *
- * \param flag_name The name of the flag without leading punctuation
- * (example: "enable_asserts").
- */
- DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name);
- /*
- * ========
- * Isolates
- * ========
- */
- /**
- * Creates a new isolate. The new isolate becomes the current isolate.
- *
- * A snapshot can be used to restore the VM quickly to a saved state
- * and is useful for fast startup. If snapshot data is provided, the
- * isolate will be started using that snapshot data. Requires a core snapshot or
- * an app snapshot created by Dart_CreateSnapshot or
- * Dart_CreatePrecompiledSnapshot* from a VM with the same version.
- *
- * Requires there to be no current isolate.
- *
- * \param script_uri The main source file or snapshot this isolate will load.
- * The VM will provide this URI to the Dart_IsolateGroupCreateCallback when a
- * child isolate is created by Isolate.spawn. The embedder should use a URI
- * that allows it to load the same program into such a child isolate.
- * \param name A short name for the isolate to improve debugging messages.
- * Typically of the format 'foo.dart:main()'.
- * \param isolate_snapshot_data Buffer containing the snapshot data of the
- * isolate or NULL if no snapshot is provided. If provided, the buffer must
- * remain valid until the isolate shuts down.
- * \param isolate_snapshot_instructions Buffer containing the snapshot
- * instructions of the isolate or NULL if no snapshot is provided. If
- * provided, the buffer must remain valid until the isolate shuts down.
- * \param flags Pointer to VM specific flags or NULL for default flags.
- * \param isolate_group_data Embedder group data. This data can be obtained
- * by calling Dart_IsolateGroupData and will be passed to the
- * Dart_IsolateShutdownCallback, Dart_IsolateCleanupCallback, and
- * Dart_IsolateGroupCleanupCallback.
- * \param isolate_data Embedder data. This data will be passed to
- * the Dart_IsolateGroupCreateCallback when new isolates are spawned from
- * this parent isolate.
- * \param error Returns NULL if creation is successful, an error message
- * otherwise. The caller is responsible for calling free() on the error
- * message.
- *
- * \return The new isolate on success, or NULL if isolate creation failed.
- */
- DART_EXPORT Dart_Isolate
- Dart_CreateIsolateGroup(const char* script_uri,
- const char* name,
- const uint8_t* isolate_snapshot_data,
- const uint8_t* isolate_snapshot_instructions,
- Dart_IsolateFlags* flags,
- void* isolate_group_data,
- void* isolate_data,
- char** error);
- /**
- * Creates a new isolate inside the isolate group of [group_member].
- *
- * Requires there to be no current isolate.
- *
- * \param group_member An isolate from the same group into which the newly created
- * isolate should be born into. Other threads may not have entered / enter this
- * member isolate.
- * \param name A short name for the isolate for debugging purposes.
- * \param shutdown_callback A callback to be called when the isolate is being
- * shutdown (may be NULL).
- * \param cleanup_callback A callback to be called when the isolate is being
- * cleaned up (may be NULL).
- * \param child_isolate_data The embedder-specific data associated with this isolate.
- * \param error Set to NULL if creation is successful, set to an error
- * message otherwise. The caller is responsible for calling free() on the
- * error message.
- *
- * \return The newly created isolate on success, or NULL if isolate creation
- * failed.
- *
- * If successful, the newly created isolate will become the current isolate.
- */
- DART_EXPORT Dart_Isolate
- Dart_CreateIsolateInGroup(Dart_Isolate group_member,
- const char* name,
- Dart_IsolateShutdownCallback shutdown_callback,
- Dart_IsolateCleanupCallback cleanup_callback,
- void* child_isolate_data,
- char** error);
- /* TODO(turnidge): Document behavior when there is already a current
- * isolate. */
- /**
- * Creates a new isolate from a Dart Kernel file. The new isolate
- * becomes the current isolate.
- *
- * Requires there to be no current isolate.
- *
- * \param script_uri The main source file or snapshot this isolate will load.
- * The VM will provide this URI to the Dart_IsolateGroupCreateCallback when a
- * child isolate is created by Isolate.spawn. The embedder should use a URI that
- * allows it to load the same program into such a child isolate.
- * \param name A short name for the isolate to improve debugging messages.
- * Typically of the format 'foo.dart:main()'.
- * \param kernel_buffer A buffer which contains a kernel/DIL program. Must
- * remain valid until isolate shutdown.
- * \param kernel_buffer_size The size of `kernel_buffer`.
- * \param flags Pointer to VM specific flags or NULL for default flags.
- * \param isolate_group_data Embedder group data. This data can be obtained
- * by calling Dart_IsolateGroupData and will be passed to the
- * Dart_IsolateShutdownCallback, Dart_IsolateCleanupCallback, and
- * Dart_IsolateGroupCleanupCallback.
- * \param isolate_data Embedder data. This data will be passed to
- * the Dart_IsolateGroupCreateCallback when new isolates are spawned from
- * this parent isolate.
- * \param error Returns NULL if creation is successful, an error message
- * otherwise. The caller is responsible for calling free() on the error
- * message.
- *
- * \return The new isolate on success, or NULL if isolate creation failed.
- */
- DART_EXPORT Dart_Isolate
- Dart_CreateIsolateGroupFromKernel(const char* script_uri,
- const char* name,
- const uint8_t* kernel_buffer,
- intptr_t kernel_buffer_size,
- Dart_IsolateFlags* flags,
- void* isolate_group_data,
- void* isolate_data,
- char** error);
- /**
- * Shuts down the current isolate. After this call, the current isolate is NULL.
- * Any current scopes created by Dart_EnterScope will be exited. Invokes the
- * shutdown callback and any callbacks of remaining weak persistent handles.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT void Dart_ShutdownIsolate(void);
- /* TODO(turnidge): Document behavior when there is no current isolate. */
- /**
- * Returns the current isolate. Will return NULL if there is no
- * current isolate.
- */
- DART_EXPORT Dart_Isolate Dart_CurrentIsolate(void);
- /**
- * Returns the callback data associated with the current isolate. This
- * data was set when the isolate got created or initialized.
- */
- DART_EXPORT void* Dart_CurrentIsolateData(void);
- /**
- * Returns the callback data associated with the given isolate. This
- * data was set when the isolate got created or initialized.
- */
- DART_EXPORT void* Dart_IsolateData(Dart_Isolate isolate);
- /**
- * Returns the current isolate group. Will return NULL if there is no
- * current isolate group.
- */
- DART_EXPORT Dart_IsolateGroup Dart_CurrentIsolateGroup(void);
- /**
- * Returns the callback data associated with the current isolate group. This
- * data was passed to the isolate group when it was created.
- */
- DART_EXPORT void* Dart_CurrentIsolateGroupData(void);
- /**
- * Gets an id that uniquely identifies current isolate group.
- *
- * It is the responsibility of the caller to free the returned ID.
- */
- typedef int64_t Dart_IsolateGroupId;
- DART_EXPORT Dart_IsolateGroupId Dart_CurrentIsolateGroupId(void);
- /**
- * Returns the callback data associated with the specified isolate group. This
- * data was passed to the isolate when it was created.
- * The embedder is responsible for ensuring the consistency of this data
- * with respect to the lifecycle of an isolate group.
- */
- DART_EXPORT void* Dart_IsolateGroupData(Dart_Isolate isolate);
- /**
- * Returns the debugging name for the current isolate.
- *
- * This name is unique to each isolate and should only be used to make
- * debugging messages more comprehensible.
- */
- DART_EXPORT Dart_Handle Dart_DebugName(void);
- /**
- * Returns the debugging name for the current isolate.
- *
- * This name is unique to each isolate and should only be used to make
- * debugging messages more comprehensible.
- *
- * The returned string is scope allocated and is only valid until the next call
- * to Dart_ExitScope.
- */
- DART_EXPORT const char* Dart_DebugNameToCString(void);
- /**
- * Returns the ID for an isolate which is used to query the service protocol.
- *
- * It is the responsibility of the caller to free the returned ID.
- */
- DART_EXPORT const char* Dart_IsolateServiceId(Dart_Isolate isolate);
- /**
- * Enters an isolate. After calling this function,
- * the current isolate will be set to the provided isolate.
- *
- * Requires there to be no current isolate. Multiple threads may not be in
- * the same isolate at once.
- */
- DART_EXPORT void Dart_EnterIsolate(Dart_Isolate isolate);
- /**
- * Kills the given isolate.
- *
- * This function has the same effect as dart:isolate's
- * Isolate.kill(priority:immediate).
- * It can interrupt ordinary Dart code but not native code. If the isolate is
- * in the middle of a long running native function, the isolate will not be
- * killed until control returns to Dart.
- *
- * Does not require a current isolate. It is safe to kill the current isolate if
- * there is one.
- */
- DART_EXPORT void Dart_KillIsolate(Dart_Isolate isolate);
- /**
- * Notifies the VM that the embedder expects to be idle until |deadline|. The VM
- * may use this time to perform garbage collection or other tasks to avoid
- * delays during execution of Dart code in the future.
- *
- * |deadline| is measured in microseconds against the system's monotonic time.
- * This clock can be accessed via Dart_TimelineGetMicros().
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT void Dart_NotifyIdle(int64_t deadline);
- typedef void (*Dart_HeapSamplingReportCallback)(void* context,
- void* data);
- typedef void* (*Dart_HeapSamplingCreateCallback)(
- Dart_Isolate isolate,
- Dart_IsolateGroup isolate_group,
- const char* cls_name,
- intptr_t allocation_size);
- typedef void (*Dart_HeapSamplingDeleteCallback)(void* data);
- /**
- * Starts the heap sampling profiler for each thread in the VM.
- */
- DART_EXPORT void Dart_EnableHeapSampling(void);
- /*
- * Stops the heap sampling profiler for each thread in the VM.
- */
- DART_EXPORT void Dart_DisableHeapSampling(void);
- /* Registers callbacks are invoked once per sampled allocation upon object
- * allocation and garbage collection.
- *
- * |create_callback| can be used to associate additional data with the sampled
- * allocation, such as a stack trace. This data pointer will be passed to
- * |delete_callback| to allow for proper disposal when the object associated
- * with the allocation sample is collected.
- *
- * The provided callbacks must not call into the VM and should do as little
- * work as possible to avoid performance penalities during object allocation and
- * garbage collection.
- *
- * NOTE: It is a fatal error to set either callback to null once they have been
- * initialized.
- */
- DART_EXPORT void Dart_RegisterHeapSamplingCallback(
- Dart_HeapSamplingCreateCallback create_callback,
- Dart_HeapSamplingDeleteCallback delete_callback);
- /*
- * Reports the surviving allocation samples for all live isolate groups in the
- * VM.
- *
- * When the callback is invoked:
- * - |context| will be the context object provided when invoking
- * |Dart_ReportSurvivingAllocations|. This can be safely set to null if not
- * required.
- * - |heap_size| will be equal to the size of the allocated object associated
- * with the sample.
- * - |cls_name| will be a C String representing
- * the class name of the allocated object. This string is valid for the
- * duration of the call to Dart_ReportSurvivingAllocations and can be
- * freed by the VM at any point after the method returns.
- * - |data| will be set to the data associated with the sample by
- * |Dart_HeapSamplingCreateCallback|.
- *
- * If |force_gc| is true, a full GC will be performed before reporting the
- * allocations.
- */
- DART_EXPORT void Dart_ReportSurvivingAllocations(
- Dart_HeapSamplingReportCallback callback,
- void* context,
- bool force_gc);
- /*
- * Sets the average heap sampling rate based on a number of |bytes| for each
- * thread.
- *
- * In other words, approximately every |bytes| allocated will create a sample.
- * Defaults to 512 KiB.
- */
- DART_EXPORT void Dart_SetHeapSamplingPeriod(intptr_t bytes);
- /**
- * Notifies the VM that the embedder expects the application's working set has
- * recently shrunk significantly and is not expected to rise in the near future.
- * The VM may spend O(heap-size) time performing clean up work.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT void Dart_NotifyDestroyed(void);
- /**
- * Notifies the VM that the system is running low on memory.
- *
- * Does not require a current isolate. Only valid after calling Dart_Initialize.
- */
- DART_EXPORT void Dart_NotifyLowMemory(void);
- typedef enum {
- /**
- * Balanced
- */
- Dart_PerformanceMode_Default,
- /**
- * Optimize for low latency, at the expense of throughput and memory overhead
- * by performing work in smaller batches (requiring more overhead) or by
- * delaying work (requiring more memory). An embedder should not remain in
- * this mode indefinitely.
- */
- Dart_PerformanceMode_Latency,
- /**
- * Optimize for high throughput, at the expense of latency and memory overhead
- * by performing work in larger batches with more intervening growth.
- */
- Dart_PerformanceMode_Throughput,
- /**
- * Optimize for low memory, at the expensive of throughput and latency by more
- * frequently performing work.
- */
- Dart_PerformanceMode_Memory,
- } Dart_PerformanceMode;
- /**
- * Set the desired performance trade-off.
- *
- * Requires a current isolate.
- *
- * Returns the previous performance mode.
- */
- DART_EXPORT Dart_PerformanceMode
- Dart_SetPerformanceMode(Dart_PerformanceMode mode);
- /**
- * Starts the CPU sampling profiler.
- */
- DART_EXPORT void Dart_StartProfiling(void);
- /**
- * Stops the CPU sampling profiler.
- *
- * Note that some profile samples might still be taken after this function
- * returns due to the asynchronous nature of the implementation on some
- * platforms.
- */
- DART_EXPORT void Dart_StopProfiling(void);
- /**
- * Notifies the VM that the current thread should not be profiled until a
- * matching call to Dart_ThreadEnableProfiling is made.
- *
- * NOTE: By default, if a thread has entered an isolate it will be profiled.
- * This function should be used when an embedder knows a thread is about
- * to make a blocking call and wants to avoid unnecessary interrupts by
- * the profiler.
- */
- DART_EXPORT void Dart_ThreadDisableProfiling(void);
- /**
- * Notifies the VM that the current thread should be profiled.
- *
- * NOTE: It is only legal to call this function *after* calling
- * Dart_ThreadDisableProfiling.
- *
- * NOTE: By default, if a thread has entered an isolate it will be profiled.
- */
- DART_EXPORT void Dart_ThreadEnableProfiling(void);
- /**
- * Register symbol information for the Dart VM's profiler and crash dumps.
- *
- * This consumes the output of //topaz/runtime/dart/profiler_symbols, which
- * should be treated as opaque.
- */
- DART_EXPORT void Dart_AddSymbols(const char* dso_name,
- void* buffer,
- intptr_t buffer_size);
- /**
- * Exits an isolate. After this call, Dart_CurrentIsolate will
- * return NULL.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT void Dart_ExitIsolate(void);
- /* TODO(turnidge): We don't want users of the api to be able to exit a
- * "pure" dart isolate. Implement and document. */
- /**
- * Creates a full snapshot of the current isolate heap.
- *
- * A full snapshot is a compact representation of the dart vm isolate heap
- * and dart isolate heap states. These snapshots are used to initialize
- * the vm isolate on startup and fast initialization of an isolate.
- * A Snapshot of the heap is created before any dart code has executed.
- *
- * Requires there to be a current isolate. Not available in the precompiled
- * runtime (check Dart_IsPrecompiledRuntime).
- *
- * \param vm_snapshot_data_buffer Returns a pointer to a buffer containing the
- * vm snapshot. This buffer is scope allocated and is only valid
- * until the next call to Dart_ExitScope.
- * \param vm_snapshot_data_size Returns the size of vm_snapshot_data_buffer.
- * \param isolate_snapshot_data_buffer Returns a pointer to a buffer containing
- * the isolate snapshot. This buffer is scope allocated and is only valid
- * until the next call to Dart_ExitScope.
- * \param isolate_snapshot_data_size Returns the size of
- * isolate_snapshot_data_buffer.
- * \param is_core Create a snapshot containing core libraries.
- * Such snapshot should be agnostic to null safety mode.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_CreateSnapshot(uint8_t** vm_snapshot_data_buffer,
- intptr_t* vm_snapshot_data_size,
- uint8_t** isolate_snapshot_data_buffer,
- intptr_t* isolate_snapshot_data_size,
- bool is_core);
- /**
- * Returns whether the buffer contains a kernel file.
- *
- * \param buffer Pointer to a buffer that might contain a kernel binary.
- * \param buffer_size Size of the buffer.
- *
- * \return Whether the buffer contains a kernel binary (full or partial).
- */
- DART_EXPORT bool Dart_IsKernel(const uint8_t* buffer, intptr_t buffer_size);
- /**
- * Make isolate runnable.
- *
- * When isolates are spawned, this function is used to indicate that
- * the creation and initialization (including script loading) of the
- * isolate is complete and the isolate can start.
- * This function expects there to be no current isolate.
- *
- * \param isolate The isolate to be made runnable.
- *
- * \return NULL if successful. Returns an error message otherwise. The caller
- * is responsible for freeing the error message.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT char* Dart_IsolateMakeRunnable(
- Dart_Isolate isolate);
- /*
- * ==================
- * Messages and Ports
- * ==================
- */
- /**
- * A port is used to send or receive inter-isolate messages
- */
- typedef int64_t Dart_Port;
- /**
- * ILLEGAL_PORT is a port number guaranteed never to be associated with a valid
- * port.
- */
- #define ILLEGAL_PORT ((Dart_Port)0)
- /**
- * A message notification callback.
- *
- * This callback allows the embedder to provide a custom wakeup mechanism for
- * the delivery of inter-isolate messages. This function is called once per
- * message on an arbitrary thread. It is the responsibility of the embedder to
- * eventually call Dart_HandleMessage once per callback received with the
- * destination isolate set as the current isolate to process the message.
- */
- typedef void (*Dart_MessageNotifyCallback)(Dart_Isolate destination_isolate);
- /**
- * Allows embedders to provide a custom wakeup mechanism for the delivery of
- * inter-isolate messages. This setting only applies to the current isolate.
- *
- * This mechanism is optional: if not provided, the isolate will be scheduled on
- * a VM-managed thread pool. An embedder should provide this callback if it
- * wants to run an isolate on a specific thread or to interleave handling of
- * inter-isolate messages with other event sources.
- *
- * Most embedders will only call this function once, before isolate
- * execution begins. If this function is called after isolate
- * execution begins, the embedder is responsible for threading issues.
- */
- DART_EXPORT void Dart_SetMessageNotifyCallback(
- Dart_MessageNotifyCallback message_notify_callback);
- /* TODO(turnidge): Consider moving this to isolate creation so that it
- * is impossible to mess up. */
- /**
- * Query the current message notify callback for the isolate.
- *
- * \return The current message notify callback for the isolate.
- */
- DART_EXPORT Dart_MessageNotifyCallback Dart_GetMessageNotifyCallback(void);
- /**
- * The VM's default message handler supports pausing an isolate before it
- * processes the first message and right after the it processes the isolate's
- * final message. This can be controlled for all isolates by two VM flags:
- *
- * `--pause-isolates-on-start`
- * `--pause-isolates-on-exit`
- *
- * Additionally, Dart_SetShouldPauseOnStart and Dart_SetShouldPauseOnExit can be
- * used to control this behaviour on a per-isolate basis.
- *
- * When an embedder is using a Dart_MessageNotifyCallback the embedder
- * needs to cooperate with the VM so that the service protocol can report
- * accurate information about isolates and so that tools such as debuggers
- * work reliably.
- *
- * The following functions can be used to implement pausing on start and exit.
- */
- /**
- * If the VM flag `--pause-isolates-on-start` was passed this will be true.
- *
- * \return A boolean value indicating if pause on start was requested.
- */
- DART_EXPORT bool Dart_ShouldPauseOnStart(void);
- /**
- * Override the VM flag `--pause-isolates-on-start` for the current isolate.
- *
- * \param should_pause Should the isolate be paused on start?
- *
- * NOTE: This must be called before Dart_IsolateMakeRunnable.
- */
- DART_EXPORT void Dart_SetShouldPauseOnStart(bool should_pause);
- /**
- * Is the current isolate paused on start?
- *
- * \return A boolean value indicating if the isolate is paused on start.
- */
- DART_EXPORT bool Dart_IsPausedOnStart(void);
- /**
- * Called when the embedder has paused the current isolate on start and when
- * the embedder has resumed the isolate.
- *
- * \param paused Is the isolate paused on start?
- */
- DART_EXPORT void Dart_SetPausedOnStart(bool paused);
- /**
- * If the VM flag `--pause-isolates-on-exit` was passed this will be true.
- *
- * \return A boolean value indicating if pause on exit was requested.
- */
- DART_EXPORT bool Dart_ShouldPauseOnExit(void);
- /**
- * Override the VM flag `--pause-isolates-on-exit` for the current isolate.
- *
- * \param should_pause Should the isolate be paused on exit?
- *
- */
- DART_EXPORT void Dart_SetShouldPauseOnExit(bool should_pause);
- /**
- * Is the current isolate paused on exit?
- *
- * \return A boolean value indicating if the isolate is paused on exit.
- */
- DART_EXPORT bool Dart_IsPausedOnExit(void);
- /**
- * Called when the embedder has paused the current isolate on exit and when
- * the embedder has resumed the isolate.
- *
- * \param paused Is the isolate paused on exit?
- */
- DART_EXPORT void Dart_SetPausedOnExit(bool paused);
- /**
- * Called when the embedder has caught a top level unhandled exception error
- * in the current isolate.
- *
- * NOTE: It is illegal to call this twice on the same isolate without first
- * clearing the sticky error to null.
- *
- * \param error The unhandled exception error.
- */
- DART_EXPORT void Dart_SetStickyError(Dart_Handle error);
- /**
- * Does the current isolate have a sticky error?
- */
- DART_EXPORT bool Dart_HasStickyError(void);
- /**
- * Gets the sticky error for the current isolate.
- *
- * \return A handle to the sticky error object or null.
- */
- DART_EXPORT Dart_Handle Dart_GetStickyError(void);
- /**
- * Handles the next pending message for the current isolate.
- *
- * May generate an unhandled exception error.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_HandleMessage(void);
- /**
- * Drains the microtask queue, then blocks the calling thread until the current
- * isolate receives a message, then handles all messages.
- *
- * \param timeout_millis When non-zero, the call returns after the indicated
- number of milliseconds even if no message was received.
- * \return A valid handle if no error occurs, otherwise an error handle.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_WaitForEvent(int64_t timeout_millis);
- /**
- * Handles any pending messages for the vm service for the current
- * isolate.
- *
- * This function may be used by an embedder at a breakpoint to avoid
- * pausing the vm service.
- *
- * This function can indirectly cause the message notify callback to
- * be called.
- *
- * \return true if the vm service requests the program resume
- * execution, false otherwise
- */
- DART_EXPORT bool Dart_HandleServiceMessages(void);
- /**
- * Does the current isolate have pending service messages?
- *
- * \return true if the isolate has pending service messages, false otherwise.
- */
- DART_EXPORT bool Dart_HasServiceMessages(void);
- /**
- * Processes any incoming messages for the current isolate.
- *
- * This function may only be used when the embedder has not provided
- * an alternate message delivery mechanism with
- * Dart_SetMessageCallbacks. It is provided for convenience.
- *
- * This function waits for incoming messages for the current
- * isolate. As new messages arrive, they are handled using
- * Dart_HandleMessage. The routine exits when all ports to the
- * current isolate are closed.
- *
- * \return A valid handle if the run loop exited successfully. If an
- * exception or other error occurs while processing messages, an
- * error handle is returned.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_RunLoop(void);
- /**
- * Lets the VM run message processing for the isolate.
- *
- * This function expects there to a current isolate and the current isolate
- * must not have an active api scope. The VM will take care of making the
- * isolate runnable (if not already), handles its message loop and will take
- * care of shutting the isolate down once it's done.
- *
- * \param errors_are_fatal Whether uncaught errors should be fatal.
- * \param on_error_port A port to notify on uncaught errors (or ILLEGAL_PORT).
- * \param on_exit_port A port to notify on exit (or ILLEGAL_PORT).
- * \param error A non-NULL pointer which will hold an error message if the call
- * fails. The error has to be free()ed by the caller.
- *
- * \return If successful the VM takes ownership of the isolate and takes care
- * of its message loop. If not successful the caller retains ownership of the
- * isolate.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT bool Dart_RunLoopAsync(
- bool errors_are_fatal,
- Dart_Port on_error_port,
- Dart_Port on_exit_port,
- char** error);
- /* TODO(turnidge): Should this be removed from the public api? */
- /**
- * Gets the main port id for the current isolate.
- */
- DART_EXPORT Dart_Port Dart_GetMainPortId(void);
- /**
- * Does the current isolate have live ReceivePorts?
- *
- * A ReceivePort is live when it has not been closed.
- */
- DART_EXPORT bool Dart_HasLivePorts(void);
- /**
- * Posts a message for some isolate. The message is a serialized
- * object.
- *
- * Requires there to be a current isolate.
- *
- * For posting messages outside of an isolate see \ref Dart_PostCObject.
- *
- * \param port_id The destination port.
- * \param object An object from the current isolate.
- *
- * \return True if the message was posted.
- */
- DART_EXPORT bool Dart_Post(Dart_Port port_id, Dart_Handle object);
- /**
- * Returns a new SendPort with the provided port id.
- *
- * \param port_id The destination port.
- *
- * \return A new SendPort if no errors occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewSendPort(Dart_Port port_id);
- /**
- * Gets the SendPort id for the provided SendPort.
- * \param port A SendPort object whose id is desired.
- * \param port_id Returns the id of the SendPort.
- * \return Success if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_SendPortGetId(Dart_Handle port,
- Dart_Port* port_id);
- /*
- * ======
- * Scopes
- * ======
- */
- /**
- * Enters a new scope.
- *
- * All new local handles will be created in this scope. Additionally,
- * some functions may return "scope allocated" memory which is only
- * valid within this scope.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT void Dart_EnterScope(void);
- /**
- * Exits a scope.
- *
- * The previous scope (if any) becomes the current scope.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT void Dart_ExitScope(void);
- /**
- * The Dart VM uses "zone allocation" for temporary structures. Zones
- * support very fast allocation of small chunks of memory. The chunks
- * cannot be deallocated individually, but instead zones support
- * deallocating all chunks in one fast operation.
- *
- * This function makes it possible for the embedder to allocate
- * temporary data in the VMs zone allocator.
- *
- * Zone allocation is possible:
- * 1. when inside a scope where local handles can be allocated
- * 2. when processing a message from a native port in a native port
- * handler
- *
- * All the memory allocated this way will be reclaimed either on the
- * next call to Dart_ExitScope or when the native port handler exits.
- *
- * \param size Size of the memory to allocate.
- *
- * \return A pointer to the allocated memory. NULL if allocation
- * failed. Failure might due to is no current VM zone.
- */
- DART_EXPORT uint8_t* Dart_ScopeAllocate(intptr_t size);
- /*
- * =======
- * Objects
- * =======
- */
- /**
- * Returns the null object.
- *
- * \return A handle to the null object.
- */
- DART_EXPORT Dart_Handle Dart_Null(void);
- /**
- * Is this object null?
- */
- DART_EXPORT bool Dart_IsNull(Dart_Handle object);
- /**
- * Returns the empty string object.
- *
- * \return A handle to the empty string object.
- */
- DART_EXPORT Dart_Handle Dart_EmptyString(void);
- /**
- * Returns types that are not classes, and which therefore cannot be looked up
- * as library members by Dart_GetType.
- *
- * \return A handle to the dynamic, void or Never type.
- */
- DART_EXPORT Dart_Handle Dart_TypeDynamic(void);
- DART_EXPORT Dart_Handle Dart_TypeVoid(void);
- DART_EXPORT Dart_Handle Dart_TypeNever(void);
- /**
- * Checks if the two objects are equal.
- *
- * The result of the comparison is returned through the 'equal'
- * parameter. The return value itself is used to indicate success or
- * failure, not equality.
- *
- * May generate an unhandled exception error.
- *
- * \param obj1 An object to be compared.
- * \param obj2 An object to be compared.
- * \param equal Returns the result of the equality comparison.
- *
- * \return A valid handle if no error occurs during the comparison.
- */
- DART_EXPORT Dart_Handle Dart_ObjectEquals(Dart_Handle obj1,
- Dart_Handle obj2,
- bool* equal);
- /**
- * Is this object an instance of some type?
- *
- * The result of the test is returned through the 'instanceof' parameter.
- * The return value itself is used to indicate success or failure.
- *
- * \param object An object.
- * \param type A type.
- * \param instanceof Return true if 'object' is an instance of type 'type'.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_ObjectIsType(Dart_Handle object,
- Dart_Handle type,
- bool* instanceof);
- /**
- * Query object type.
- *
- * \param object Some Object.
- *
- * \return true if Object is of the specified type.
- */
- DART_EXPORT bool Dart_IsInstance(Dart_Handle object);
- DART_EXPORT bool Dart_IsNumber(Dart_Handle object);
- DART_EXPORT bool Dart_IsInteger(Dart_Handle object);
- DART_EXPORT bool Dart_IsDouble(Dart_Handle object);
- DART_EXPORT bool Dart_IsBoolean(Dart_Handle object);
- DART_EXPORT bool Dart_IsString(Dart_Handle object);
- DART_EXPORT bool Dart_IsStringLatin1(Dart_Handle object); /* (ISO-8859-1) */
- DART_EXPORT bool Dart_IsExternalString(Dart_Handle object);
- DART_EXPORT bool Dart_IsList(Dart_Handle object);
- DART_EXPORT bool Dart_IsMap(Dart_Handle object);
- DART_EXPORT bool Dart_IsLibrary(Dart_Handle object);
- DART_EXPORT bool Dart_IsType(Dart_Handle handle);
- DART_EXPORT bool Dart_IsFunction(Dart_Handle handle);
- DART_EXPORT bool Dart_IsVariable(Dart_Handle handle);
- DART_EXPORT bool Dart_IsTypeVariable(Dart_Handle handle);
- DART_EXPORT bool Dart_IsClosure(Dart_Handle object);
- DART_EXPORT bool Dart_IsTypedData(Dart_Handle object);
- DART_EXPORT bool Dart_IsByteBuffer(Dart_Handle object);
- DART_EXPORT bool Dart_IsFuture(Dart_Handle object);
- /*
- * =========
- * Instances
- * =========
- */
- /*
- * For the purposes of the embedding api, not all objects returned are
- * Dart language objects. Within the api, we use the term 'Instance'
- * to indicate handles which refer to true Dart language objects.
- *
- * TODO(turnidge): Reorganize the "Object" section above, pulling down
- * any functions that more properly belong here. */
- /**
- * Gets the type of a Dart language object.
- *
- * \param instance Some Dart object.
- *
- * \return If no error occurs, the type is returned. Otherwise an
- * error handle is returned.
- */
- DART_EXPORT Dart_Handle Dart_InstanceGetType(Dart_Handle instance);
- /**
- * Returns the name for the provided class type.
- *
- * \return A valid string handle if no error occurs during the
- * operation.
- */
- DART_EXPORT Dart_Handle Dart_ClassName(Dart_Handle cls_type);
- /**
- * Returns the name for the provided function or method.
- *
- * \return A valid string handle if no error occurs during the
- * operation.
- */
- DART_EXPORT Dart_Handle Dart_FunctionName(Dart_Handle function);
- /**
- * Returns a handle to the owner of a function.
- *
- * The owner of an instance method or a static method is its defining
- * class. The owner of a top-level function is its defining
- * library. The owner of the function of a non-implicit closure is the
- * function of the method or closure that defines the non-implicit
- * closure.
- *
- * \return A valid handle to the owner of the function, or an error
- * handle if the argument is not a valid handle to a function.
- */
- DART_EXPORT Dart_Handle Dart_FunctionOwner(Dart_Handle function);
- /**
- * Determines whether a function handle refers to a static function
- * of method.
- *
- * For the purposes of the embedding API, a top-level function is
- * implicitly declared static.
- *
- * \param function A handle to a function or method declaration.
- * \param is_static Returns whether the function or method is declared static.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_FunctionIsStatic(Dart_Handle function,
- bool* is_static);
- /**
- * Is this object a closure resulting from a tear-off (closurized method)?
- *
- * Returns true for closures produced when an ordinary method is accessed
- * through a getter call. Returns false otherwise, in particular for closures
- * produced from local function declarations.
- *
- * \param object Some Object.
- *
- * \return true if Object is a tear-off.
- */
- DART_EXPORT bool Dart_IsTearOff(Dart_Handle object);
- /**
- * Retrieves the function of a closure.
- *
- * \return A handle to the function of the closure, or an error handle if the
- * argument is not a closure.
- */
- DART_EXPORT Dart_Handle Dart_ClosureFunction(Dart_Handle closure);
- /**
- * Returns a handle to the library which contains class.
- *
- * \return A valid handle to the library with owns class, null if the class
- * has no library or an error handle if the argument is not a valid handle
- * to a class type.
- */
- DART_EXPORT Dart_Handle Dart_ClassLibrary(Dart_Handle cls_type);
- /*
- * =============================
- * Numbers, Integers and Doubles
- * =============================
- */
- /**
- * Does this Integer fit into a 64-bit signed integer?
- *
- * \param integer An integer.
- * \param fits Returns true if the integer fits into a 64-bit signed integer.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_IntegerFitsIntoInt64(Dart_Handle integer,
- bool* fits);
- /**
- * Does this Integer fit into a 64-bit unsigned integer?
- *
- * \param integer An integer.
- * \param fits Returns true if the integer fits into a 64-bit unsigned integer.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_IntegerFitsIntoUint64(Dart_Handle integer,
- bool* fits);
- /**
- * Returns an Integer with the provided value.
- *
- * \param value The value of the integer.
- *
- * \return The Integer object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewInteger(int64_t value);
- /**
- * Returns an Integer with the provided value.
- *
- * \param value The unsigned value of the integer.
- *
- * \return The Integer object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewIntegerFromUint64(uint64_t value);
- /**
- * Returns an Integer with the provided value.
- *
- * \param value The value of the integer represented as a C string
- * containing a hexadecimal number.
- *
- * \return The Integer object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewIntegerFromHexCString(const char* value);
- /**
- * Gets the value of an Integer.
- *
- * The integer must fit into a 64-bit signed integer, otherwise an error occurs.
- *
- * \param integer An Integer.
- * \param value Returns the value of the Integer.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_IntegerToInt64(Dart_Handle integer,
- int64_t* value);
- /**
- * Gets the value of an Integer.
- *
- * The integer must fit into a 64-bit unsigned integer, otherwise an
- * error occurs.
- *
- * \param integer An Integer.
- * \param value Returns the value of the Integer.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_IntegerToUint64(Dart_Handle integer,
- uint64_t* value);
- /**
- * Gets the value of an integer as a hexadecimal C string.
- *
- * \param integer An Integer.
- * \param value Returns the value of the Integer as a hexadecimal C
- * string. This C string is scope allocated and is only valid until
- * the next call to Dart_ExitScope.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_IntegerToHexCString(Dart_Handle integer,
- const char** value);
- /**
- * Returns a Double with the provided value.
- *
- * \param value A double.
- *
- * \return The Double object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewDouble(double value);
- /**
- * Gets the value of a Double
- *
- * \param double_obj A Double
- * \param value Returns the value of the Double.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_DoubleValue(Dart_Handle double_obj, double* value);
- /**
- * Returns a closure of static function 'function_name' in the class 'class_name'
- * in the exported namespace of specified 'library'.
- *
- * \param library Library object
- * \param cls_type Type object representing a Class
- * \param function_name Name of the static function in the class
- *
- * \return A valid Dart instance if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_GetStaticMethodClosure(Dart_Handle library,
- Dart_Handle cls_type,
- Dart_Handle function_name);
- /*
- * ========
- * Booleans
- * ========
- */
- /**
- * Returns the True object.
- *
- * Requires there to be a current isolate.
- *
- * \return A handle to the True object.
- */
- DART_EXPORT Dart_Handle Dart_True(void);
- /**
- * Returns the False object.
- *
- * Requires there to be a current isolate.
- *
- * \return A handle to the False object.
- */
- DART_EXPORT Dart_Handle Dart_False(void);
- /**
- * Returns a Boolean with the provided value.
- *
- * \param value true or false.
- *
- * \return The Boolean object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewBoolean(bool value);
- /**
- * Gets the value of a Boolean
- *
- * \param boolean_obj A Boolean
- * \param value Returns the value of the Boolean.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_BooleanValue(Dart_Handle boolean_obj, bool* value);
- /*
- * =======
- * Strings
- * =======
- */
- /**
- * Gets the length of a String.
- *
- * \param str A String.
- * \param length Returns the length of the String.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_StringLength(Dart_Handle str, intptr_t* length);
- /**
- * Returns a String built from the provided C string
- * (There is an implicit assumption that the C string passed in contains
- * UTF-8 encoded characters and '\0' is considered as a termination
- * character).
- *
- * \param str A C String
- *
- * \return The String object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewStringFromCString(const char* str);
- /* TODO(turnidge): Document what happens when we run out of memory
- * during this call. */
- /**
- * Returns a String built from an array of UTF-8 encoded characters.
- *
- * \param utf8_array An array of UTF-8 encoded characters.
- * \param length The length of the codepoints array.
- *
- * \return The String object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewStringFromUTF8(const uint8_t* utf8_array,
- intptr_t length);
- /**
- * Returns a String built from an array of UTF-16 encoded characters.
- *
- * \param utf16_array An array of UTF-16 encoded characters.
- * \param length The length of the codepoints array.
- *
- * \return The String object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewStringFromUTF16(const uint16_t* utf16_array,
- intptr_t length);
- /**
- * Returns a String built from an array of UTF-32 encoded characters.
- *
- * \param utf32_array An array of UTF-32 encoded characters.
- * \param length The length of the codepoints array.
- *
- * \return The String object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewStringFromUTF32(const int32_t* utf32_array,
- intptr_t length);
- /**
- * Returns a String which references an external array of
- * Latin-1 (ISO-8859-1) encoded characters.
- *
- * \param latin1_array Array of Latin-1 encoded characters. This must not move.
- * \param length The length of the characters array.
- * \param peer An external pointer to associate with this string.
- * \param external_allocation_size The number of externally allocated
- * bytes for peer. Used to inform the garbage collector.
- * \param callback A callback to be called when this string is finalized.
- *
- * \return The String object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle
- Dart_NewExternalLatin1String(const uint8_t* latin1_array,
- intptr_t length,
- void* peer,
- intptr_t external_allocation_size,
- Dart_HandleFinalizer callback);
- /**
- * Returns a String which references an external array of UTF-16 encoded
- * characters.
- *
- * \param utf16_array An array of UTF-16 encoded characters. This must not move.
- * \param length The length of the characters array.
- * \param peer An external pointer to associate with this string.
- * \param external_allocation_size The number of externally allocated
- * bytes for peer. Used to inform the garbage collector.
- * \param callback A callback to be called when this string is finalized.
- *
- * \return The String object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle
- Dart_NewExternalUTF16String(const uint16_t* utf16_array,
- intptr_t length,
- void* peer,
- intptr_t external_allocation_size,
- Dart_HandleFinalizer callback);
- /**
- * Gets the C string representation of a String.
- * (It is a sequence of UTF-8 encoded values with a '\0' termination.)
- *
- * \param str A string.
- * \param cstr Returns the String represented as a C string.
- * This C string is scope allocated and is only valid until
- * the next call to Dart_ExitScope.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_StringToCString(Dart_Handle str,
- const char** cstr);
- /**
- * Gets a UTF-8 encoded representation of a String.
- *
- * Any unpaired surrogate code points in the string will be converted as
- * replacement characters (U+FFFD, 0xEF 0xBF 0xBD in UTF-8). If you need
- * to preserve unpaired surrogates, use the Dart_StringToUTF16 function.
- *
- * \param str A string.
- * \param utf8_array Returns the String represented as UTF-8 code
- * units. This UTF-8 array is scope allocated and is only valid
- * until the next call to Dart_ExitScope.
- * \param length Used to return the length of the array which was
- * actually used.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_StringToUTF8(Dart_Handle str,
- uint8_t** utf8_array,
- intptr_t* length);
- /**
- * Gets the data corresponding to the string object. This function returns
- * the data only for Latin-1 (ISO-8859-1) string objects. For all other
- * string objects it returns an error.
- *
- * \param str A string.
- * \param latin1_array An array allocated by the caller, used to return
- * the string data.
- * \param length Used to pass in the length of the provided array.
- * Used to return the length of the array which was actually used.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_StringToLatin1(Dart_Handle str,
- uint8_t* latin1_array,
- intptr_t* length);
- /**
- * Gets the UTF-16 encoded representation of a string.
- *
- * \param str A string.
- * \param utf16_array An array allocated by the caller, used to return
- * the array of UTF-16 encoded characters.
- * \param length Used to pass in the length of the provided array.
- * Used to return the length of the array which was actually used.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_StringToUTF16(Dart_Handle str,
- uint16_t* utf16_array,
- intptr_t* length);
- /**
- * Gets the storage size in bytes of a String.
- *
- * \param str A String.
- * \param size Returns the storage size in bytes of the String.
- * This is the size in bytes needed to store the String.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_StringStorageSize(Dart_Handle str, intptr_t* size);
- /**
- * Retrieves some properties associated with a String.
- * Properties retrieved are:
- * - character size of the string (one or two byte)
- * - length of the string
- * - peer pointer of string if it is an external string.
- * \param str A String.
- * \param char_size Returns the character size of the String.
- * \param str_len Returns the length of the String.
- * \param peer Returns the peer pointer associated with the String or 0 if
- * there is no peer pointer for it.
- * \return Success if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_StringGetProperties(Dart_Handle str,
- intptr_t* char_size,
- intptr_t* str_len,
- void** peer);
- /*
- * =====
- * Lists
- * =====
- */
- /**
- * Returns a List<dynamic> of the desired length.
- *
- * \param length The length of the list.
- *
- * \return The List object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewList(intptr_t length);
- typedef enum {
- Dart_CoreType_Dynamic,
- Dart_CoreType_Int,
- Dart_CoreType_String,
- } Dart_CoreType_Id;
- // TODO(bkonyi): convert this to use nullable types once NNBD is enabled.
- /**
- * Returns a List of the desired length with the desired legacy element type.
- *
- * \param element_type_id The type of elements of the list.
- * \param length The length of the list.
- *
- * \return The List object if no error occurs. Otherwise returns an error
- * handle.
- */
- DART_EXPORT Dart_Handle Dart_NewListOf(Dart_CoreType_Id element_type_id,
- intptr_t length);
- /**
- * Returns a List of the desired length with the desired element type.
- *
- * \param element_type Handle to a nullable type object. E.g., from
- * Dart_GetType or Dart_GetNullableType.
- *
- * \param length The length of the list.
- *
- * \return The List object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewListOfType(Dart_Handle element_type,
- intptr_t length);
- /**
- * Returns a List of the desired length with the desired element type, filled
- * with the provided object.
- *
- * \param element_type Handle to a type object. E.g., from Dart_GetType.
- *
- * \param fill_object Handle to an object of type 'element_type' that will be
- * used to populate the list. This parameter can only be Dart_Null() if the
- * length of the list is 0 or 'element_type' is a nullable type.
- *
- * \param length The length of the list.
- *
- * \return The List object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewListOfTypeFilled(Dart_Handle element_type,
- Dart_Handle fill_object,
- intptr_t length);
- /**
- * Gets the length of a List.
- *
- * May generate an unhandled exception error.
- *
- * \param list A List.
- * \param length Returns the length of the List.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_ListLength(Dart_Handle list, intptr_t* length);
- /**
- * Gets the Object at some index of a List.
- *
- * If the index is out of bounds, an error occurs.
- *
- * May generate an unhandled exception error.
- *
- * \param list A List.
- * \param index A valid index into the List.
- *
- * \return The Object in the List at the specified index if no error
- * occurs. Otherwise returns an error handle.
- */
- DART_EXPORT Dart_Handle Dart_ListGetAt(Dart_Handle list, intptr_t index);
- /**
- * Gets a range of Objects from a List.
- *
- * If any of the requested index values are out of bounds, an error occurs.
- *
- * May generate an unhandled exception error.
- *
- * \param list A List.
- * \param offset The offset of the first item to get.
- * \param length The number of items to get.
- * \param result A pointer to fill with the objects.
- *
- * \return Success if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_ListGetRange(Dart_Handle list,
- intptr_t offset,
- intptr_t length,
- Dart_Handle* result);
- /**
- * Sets the Object at some index of a List.
- *
- * If the index is out of bounds, an error occurs.
- *
- * May generate an unhandled exception error.
- *
- * \param list A List.
- * \param index A valid index into the List.
- * \param value The Object to put in the List.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT Dart_Handle Dart_ListSetAt(Dart_Handle list,
- intptr_t index,
- Dart_Handle value);
- /**
- * May generate an unhandled exception error.
- */
- DART_EXPORT Dart_Handle Dart_ListGetAsBytes(Dart_Handle list,
- intptr_t offset,
- uint8_t* native_array,
- intptr_t length);
- /**
- * May generate an unhandled exception error.
- */
- DART_EXPORT Dart_Handle Dart_ListSetAsBytes(Dart_Handle list,
- intptr_t offset,
- const uint8_t* native_array,
- intptr_t length);
- /*
- * ====
- * Maps
- * ====
- */
- /**
- * Gets the Object at some key of a Map.
- *
- * May generate an unhandled exception error.
- *
- * \param map A Map.
- * \param key An Object.
- *
- * \return The value in the map at the specified key, null if the map does not
- * contain the key, or an error handle.
- */
- DART_EXPORT Dart_Handle Dart_MapGetAt(Dart_Handle map, Dart_Handle key);
- /**
- * Returns whether the Map contains a given key.
- *
- * May generate an unhandled exception error.
- *
- * \param map A Map.
- *
- * \return A handle on a boolean indicating whether map contains the key.
- * Otherwise returns an error handle.
- */
- DART_EXPORT Dart_Handle Dart_MapContainsKey(Dart_Handle map, Dart_Handle key);
- /**
- * Gets the list of keys of a Map.
- *
- * May generate an unhandled exception error.
- *
- * \param map A Map.
- *
- * \return The list of key Objects if no error occurs. Otherwise returns an
- * error handle.
- */
- DART_EXPORT Dart_Handle Dart_MapKeys(Dart_Handle map);
- /*
- * ==========
- * Typed Data
- * ==========
- */
- typedef enum {
- Dart_TypedData_kByteData = 0,
- Dart_TypedData_kInt8,
- Dart_TypedData_kUint8,
- Dart_TypedData_kUint8Clamped,
- Dart_TypedData_kInt16,
- Dart_TypedData_kUint16,
- Dart_TypedData_kInt32,
- Dart_TypedData_kUint32,
- Dart_TypedData_kInt64,
- Dart_TypedData_kUint64,
- Dart_TypedData_kFloat32,
- Dart_TypedData_kFloat64,
- Dart_TypedData_kInt32x4,
- Dart_TypedData_kFloat32x4,
- Dart_TypedData_kFloat64x2,
- Dart_TypedData_kInvalid
- } Dart_TypedData_Type;
- /**
- * Return type if this object is a TypedData object.
- *
- * \return kInvalid if the object is not a TypedData object or the appropriate
- * Dart_TypedData_Type.
- */
- DART_EXPORT Dart_TypedData_Type Dart_GetTypeOfTypedData(Dart_Handle object);
- /**
- * Return type if this object is an external TypedData object.
- *
- * \return kInvalid if the object is not an external TypedData object or
- * the appropriate Dart_TypedData_Type.
- */
- DART_EXPORT Dart_TypedData_Type
- Dart_GetTypeOfExternalTypedData(Dart_Handle object);
- /**
- * Returns a TypedData object of the desired length and type.
- *
- * \param type The type of the TypedData object.
- * \param length The length of the TypedData object (length in type units).
- *
- * \return The TypedData object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewTypedData(Dart_TypedData_Type type,
- intptr_t length);
- /**
- * Returns a TypedData object which references an external data array.
- *
- * \param type The type of the data array.
- * \param data A data array. This array must not move.
- * \param length The length of the data array (length in type units).
- *
- * \return The TypedData object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewExternalTypedData(Dart_TypedData_Type type,
- void* data,
- intptr_t length);
- /**
- * Returns a TypedData object which references an external data array.
- *
- * \param type The type of the data array.
- * \param data A data array. This array must not move.
- * \param length The length of the data array (length in type units).
- * \param peer A pointer to a native object or NULL. This value is
- * provided to callback when it is invoked.
- * \param external_allocation_size The number of externally allocated
- * bytes for peer. Used to inform the garbage collector.
- * \param callback A function pointer that will be invoked sometime
- * after the object is garbage collected, unless the handle has been deleted.
- * A valid callback needs to be specified it cannot be NULL.
- *
- * \return The TypedData object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle
- Dart_NewExternalTypedDataWithFinalizer(Dart_TypedData_Type type,
- void* data,
- intptr_t length,
- void* peer,
- intptr_t external_allocation_size,
- Dart_HandleFinalizer callback);
- DART_EXPORT Dart_Handle Dart_NewUnmodifiableExternalTypedDataWithFinalizer(
- Dart_TypedData_Type type,
- const void* data,
- intptr_t length,
- void* peer,
- intptr_t external_allocation_size,
- Dart_HandleFinalizer callback);
- /**
- * Returns a ByteBuffer object for the typed data.
- *
- * \param typed_data The TypedData object.
- *
- * \return The ByteBuffer object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewByteBuffer(Dart_Handle typed_data);
- /**
- * Acquires access to the internal data address of a TypedData object.
- *
- * \param object The typed data object whose internal data address is to
- * be accessed.
- * \param type The type of the object is returned here.
- * \param data The internal data address is returned here.
- * \param len Size of the typed array is returned here.
- *
- * Notes:
- * When the internal address of the object is acquired any calls to a
- * Dart API function that could potentially allocate an object or run
- * any Dart code will return an error.
- *
- * Any Dart API functions for accessing the data should not be called
- * before the corresponding release. In particular, the object should
- * not be acquired again before its release. This leads to undefined
- * behavior.
- *
- * \return Success if the internal data address is acquired successfully.
- * Otherwise, returns an error handle.
- */
- DART_EXPORT Dart_Handle Dart_TypedDataAcquireData(Dart_Handle object,
- Dart_TypedData_Type* type,
- void** data,
- intptr_t* len);
- /**
- * Releases access to the internal data address that was acquired earlier using
- * Dart_TypedDataAcquireData.
- *
- * \param object The typed data object whose internal data address is to be
- * released.
- *
- * \return Success if the internal data address is released successfully.
- * Otherwise, returns an error handle.
- */
- DART_EXPORT Dart_Handle Dart_TypedDataReleaseData(Dart_Handle object);
- /**
- * Returns the TypedData object associated with the ByteBuffer object.
- *
- * \param byte_buffer The ByteBuffer object.
- *
- * \return The TypedData object if no error occurs. Otherwise returns
- * an error handle.
- */
- DART_EXPORT Dart_Handle Dart_GetDataFromByteBuffer(Dart_Handle byte_buffer);
- /*
- * ============================================================
- * Invoking Constructors, Methods, Closures and Field accessors
- * ============================================================
- */
- /**
- * Invokes a constructor, creating a new object.
- *
- * This function allows hidden constructors (constructors with leading
- * underscores) to be called.
- *
- * \param type Type of object to be constructed.
- * \param constructor_name The name of the constructor to invoke. Use
- * Dart_Null() or Dart_EmptyString() to invoke the unnamed constructor.
- * This name should not include the name of the class.
- * \param number_of_arguments Size of the arguments array.
- * \param arguments An array of arguments to the constructor.
- *
- * \return If the constructor is called and completes successfully,
- * then the new object. If an error occurs during execution, then an
- * error handle is returned.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_New(Dart_Handle type,
- Dart_Handle constructor_name,
- int number_of_arguments,
- Dart_Handle* arguments);
- /**
- * Allocate a new object without invoking a constructor.
- *
- * \param type The type of an object to be allocated.
- *
- * \return The new object. If an error occurs during execution, then an
- * error handle is returned.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_Allocate(Dart_Handle type);
- /**
- * Allocate a new object without invoking a constructor, and sets specified
- * native fields.
- *
- * \param type The type of an object to be allocated.
- * \param num_native_fields The number of native fields to set.
- * \param native_fields An array containing the value of native fields.
- *
- * \return The new object. If an error occurs during execution, then an
- * error handle is returned.
- */
- DART_EXPORT Dart_Handle
- Dart_AllocateWithNativeFields(Dart_Handle type,
- intptr_t num_native_fields,
- const intptr_t* native_fields);
- /**
- * Invokes a method or function.
- *
- * The 'target' parameter may be an object, type, or library. If
- * 'target' is an object, then this function will invoke an instance
- * method. If 'target' is a type, then this function will invoke a
- * static method. If 'target' is a library, then this function will
- * invoke a top-level function from that library.
- * NOTE: This API call cannot be used to invoke methods of a type object.
- *
- * This function ignores visibility (leading underscores in names).
- *
- * May generate an unhandled exception error.
- *
- * \param target An object, type, or library.
- * \param name The name of the function or method to invoke.
- * \param number_of_arguments Size of the arguments array.
- * \param arguments An array of arguments to the function.
- *
- * \return If the function or method is called and completes
- * successfully, then the return value is returned. If an error
- * occurs during execution, then an error handle is returned.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_Invoke(Dart_Handle target,
- Dart_Handle name,
- int number_of_arguments,
- Dart_Handle* arguments);
- /* TODO(turnidge): Document how to invoke operators. */
- /**
- * Invokes a Closure with the given arguments.
- *
- * May generate an unhandled exception error.
- *
- * \return If no error occurs during execution, then the result of
- * invoking the closure is returned. If an error occurs during
- * execution, then an error handle is returned.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_InvokeClosure(Dart_Handle closure,
- int number_of_arguments,
- Dart_Handle* arguments);
- /**
- * Invokes a Generative Constructor on an object that was previously
- * allocated using Dart_Allocate/Dart_AllocateWithNativeFields.
- *
- * The 'object' parameter must be an object.
- *
- * This function ignores visibility (leading underscores in names).
- *
- * May generate an unhandled exception error.
- *
- * \param object An object.
- * \param name The name of the constructor to invoke.
- * Use Dart_Null() or Dart_EmptyString() to invoke the unnamed constructor.
- * \param number_of_arguments Size of the arguments array.
- * \param arguments An array of arguments to the function.
- *
- * \return If the constructor is called and completes
- * successfully, then the object is returned. If an error
- * occurs during execution, then an error handle is returned.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_InvokeConstructor(Dart_Handle object,
- Dart_Handle name,
- int number_of_arguments,
- Dart_Handle* arguments);
- /**
- * Gets the value of a field.
- *
- * The 'container' parameter may be an object, type, or library. If
- * 'container' is an object, then this function will access an
- * instance field. If 'container' is a type, then this function will
- * access a static field. If 'container' is a library, then this
- * function will access a top-level variable.
- * NOTE: This API call cannot be used to access fields of a type object.
- *
- * This function ignores field visibility (leading underscores in names).
- *
- * May generate an unhandled exception error.
- *
- * \param container An object, type, or library.
- * \param name A field name.
- *
- * \return If no error occurs, then the value of the field is
- * returned. Otherwise an error handle is returned.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_GetField(Dart_Handle container, Dart_Handle name);
- /**
- * Sets the value of a field.
- *
- * The 'container' parameter may actually be an object, type, or
- * library. If 'container' is an object, then this function will
- * access an instance field. If 'container' is a type, then this
- * function will access a static field. If 'container' is a library,
- * then this function will access a top-level variable.
- * NOTE: This API call cannot be used to access fields of a type object.
- *
- * This function ignores field visibility (leading underscores in names).
- *
- * May generate an unhandled exception error.
- *
- * \param container An object, type, or library.
- * \param name A field name.
- * \param value The new field value.
- *
- * \return A valid handle if no error occurs.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_SetField(Dart_Handle container, Dart_Handle name, Dart_Handle value);
- /*
- * ==========
- * Exceptions
- * ==========
- */
- /*
- * TODO(turnidge): Remove these functions from the api and replace all
- * uses with Dart_NewUnhandledExceptionError. */
- /**
- * Throws an exception.
- *
- * This function causes a Dart language exception to be thrown. This
- * will proceed in the standard way, walking up Dart frames until an
- * appropriate 'catch' block is found, executing 'finally' blocks,
- * etc.
- *
- * If an error handle is passed into this function, the error is
- * propagated immediately. See Dart_PropagateError for a discussion
- * of error propagation.
- *
- * If successful, this function does not return. Note that this means
- * that the destructors of any stack-allocated C++ objects will not be
- * called. If there are no Dart frames on the stack, an error occurs.
- *
- * \return An error handle if the exception was not thrown.
- * Otherwise the function does not return.
- */
- DART_EXPORT Dart_Handle Dart_ThrowException(Dart_Handle exception);
- /**
- * Rethrows an exception.
- *
- * Rethrows an exception, unwinding all dart frames on the stack. If
- * successful, this function does not return. Note that this means
- * that the destructors of any stack-allocated C++ objects will not be
- * called. If there are no Dart frames on the stack, an error occurs.
- *
- * \return An error handle if the exception was not thrown.
- * Otherwise the function does not return.
- */
- DART_EXPORT Dart_Handle Dart_ReThrowException(Dart_Handle exception,
- Dart_Handle stacktrace);
- /*
- * ===========================
- * Native fields and functions
- * ===========================
- */
- /**
- * Gets the number of native instance fields in an object.
- */
- DART_EXPORT Dart_Handle Dart_GetNativeInstanceFieldCount(Dart_Handle obj,
- int* count);
- /**
- * Gets the value of a native field.
- *
- * TODO(turnidge): Document.
- */
- DART_EXPORT Dart_Handle Dart_GetNativeInstanceField(Dart_Handle obj,
- int index,
- intptr_t* value);
- /**
- * Sets the value of a native field.
- *
- * TODO(turnidge): Document.
- */
- DART_EXPORT Dart_Handle Dart_SetNativeInstanceField(Dart_Handle obj,
- int index,
- intptr_t value);
- /**
- * The arguments to a native function.
- *
- * This object is passed to a native function to represent its
- * arguments and return value. It allows access to the arguments to a
- * native function by index. It also allows the return value of a
- * native function to be set.
- */
- typedef struct _Dart_NativeArguments* Dart_NativeArguments;
- /**
- * Extracts current isolate group data from the native arguments structure.
- */
- DART_EXPORT void* Dart_GetNativeIsolateGroupData(Dart_NativeArguments args);
- typedef enum {
- Dart_NativeArgument_kBool = 0,
- Dart_NativeArgument_kInt32,
- Dart_NativeArgument_kUint32,
- Dart_NativeArgument_kInt64,
- Dart_NativeArgument_kUint64,
- Dart_NativeArgument_kDouble,
- Dart_NativeArgument_kString,
- Dart_NativeArgument_kInstance,
- Dart_NativeArgument_kNativeFields,
- } Dart_NativeArgument_Type;
- typedef struct _Dart_NativeArgument_Descriptor {
- uint8_t type;
- uint8_t index;
- } Dart_NativeArgument_Descriptor;
- typedef union _Dart_NativeArgument_Value {
- bool as_bool;
- int32_t as_int32;
- uint32_t as_uint32;
- int64_t as_int64;
- uint64_t as_uint64;
- double as_double;
- struct {
- Dart_Handle dart_str;
- void* peer;
- } as_string;
- struct {
- intptr_t num_fields;
- intptr_t* values;
- } as_native_fields;
- Dart_Handle as_instance;
- } Dart_NativeArgument_Value;
- enum {
- kNativeArgNumberPos = 0,
- kNativeArgNumberSize = 8,
- kNativeArgTypePos = kNativeArgNumberPos + kNativeArgNumberSize,
- kNativeArgTypeSize = 8,
- };
- #define BITMASK(size) ((1 << size) - 1)
- #define DART_NATIVE_ARG_DESCRIPTOR(type, position) \
- (((type & BITMASK(kNativeArgTypeSize)) << kNativeArgTypePos) | \
- (position & BITMASK(kNativeArgNumberSize)))
- /**
- * Gets the native arguments based on the types passed in and populates
- * the passed arguments buffer with appropriate native values.
- *
- * \param args the Native arguments block passed into the native call.
- * \param num_arguments length of argument descriptor array and argument
- * values array passed in.
- * \param arg_descriptors an array that describes the arguments that
- * need to be retrieved. For each argument to be retrieved the descriptor
- * contains the argument number (0, 1 etc.) and the argument type
- * described using Dart_NativeArgument_Type, e.g:
- * DART_NATIVE_ARG_DESCRIPTOR(Dart_NativeArgument_kBool, 1) indicates
- * that the first argument is to be retrieved and it should be a boolean.
- * \param arg_values array into which the native arguments need to be
- * extracted into, the array is allocated by the caller (it could be
- * stack allocated to avoid the malloc/free performance overhead).
- *
- * \return Success if all the arguments could be extracted correctly,
- * returns an error handle if there were any errors while extracting the
- * arguments (mismatched number of arguments, incorrect types, etc.).
- */
- DART_EXPORT Dart_Handle
- Dart_GetNativeArguments(Dart_NativeArguments args,
- int num_arguments,
- const Dart_NativeArgument_Descriptor* arg_descriptors,
- Dart_NativeArgument_Value* arg_values);
- /**
- * Gets the native argument at some index.
- */
- DART_EXPORT Dart_Handle Dart_GetNativeArgument(Dart_NativeArguments args,
- int index);
- /* TODO(turnidge): Specify the behavior of an out-of-bounds access. */
- /**
- * Gets the number of native arguments.
- */
- DART_EXPORT int Dart_GetNativeArgumentCount(Dart_NativeArguments args);
- /**
- * Gets all the native fields of the native argument at some index.
- * \param args Native arguments structure.
- * \param arg_index Index of the desired argument in the structure above.
- * \param num_fields size of the intptr_t array 'field_values' passed in.
- * \param field_values intptr_t array in which native field values are returned.
- * \return Success if the native fields where copied in successfully. Otherwise
- * returns an error handle. On success the native field values are copied
- * into the 'field_values' array, if the argument at 'arg_index' is a
- * null object then 0 is copied as the native field values into the
- * 'field_values' array.
- */
- DART_EXPORT Dart_Handle
- Dart_GetNativeFieldsOfArgument(Dart_NativeArguments args,
- int arg_index,
- int num_fields,
- intptr_t* field_values);
- /**
- * Gets the native field of the receiver.
- */
- DART_EXPORT Dart_Handle Dart_GetNativeReceiver(Dart_NativeArguments args,
- intptr_t* value);
- /**
- * Gets a string native argument at some index.
- * \param args Native arguments structure.
- * \param arg_index Index of the desired argument in the structure above.
- * \param peer Returns the peer pointer if the string argument has one.
- * \return Success if the string argument has a peer, if it does not
- * have a peer then the String object is returned. Otherwise returns
- * an error handle (argument is not a String object).
- */
- DART_EXPORT Dart_Handle Dart_GetNativeStringArgument(Dart_NativeArguments args,
- int arg_index,
- void** peer);
- /**
- * Gets an integer native argument at some index.
- * \param args Native arguments structure.
- * \param index Index of the desired argument in the structure above.
- * \param value Returns the integer value if the argument is an Integer.
- * \return Success if no error occurs. Otherwise returns an error handle.
- */
- DART_EXPORT Dart_Handle Dart_GetNativeIntegerArgument(Dart_NativeArguments args,
- int index,
- int64_t* value);
- /**
- * Gets a boolean native argument at some index.
- * \param args Native arguments structure.
- * \param index Index of the desired argument in the structure above.
- * \param value Returns the boolean value if the argument is a Boolean.
- * \return Success if no error occurs. Otherwise returns an error handle.
- */
- DART_EXPORT Dart_Handle Dart_GetNativeBooleanArgument(Dart_NativeArguments args,
- int index,
- bool* value);
- /**
- * Gets a double native argument at some index.
- * \param args Native arguments structure.
- * \param index Index of the desired argument in the structure above.
- * \param value Returns the double value if the argument is a double.
- * \return Success if no error occurs. Otherwise returns an error handle.
- */
- DART_EXPORT Dart_Handle Dart_GetNativeDoubleArgument(Dart_NativeArguments args,
- int index,
- double* value);
- /**
- * Sets the return value for a native function.
- *
- * If retval is an Error handle, then error will be propagated once
- * the native functions exits. See Dart_PropagateError for a
- * discussion of how different types of errors are propagated.
- */
- DART_EXPORT void Dart_SetReturnValue(Dart_NativeArguments args,
- Dart_Handle retval);
- DART_EXPORT void Dart_SetWeakHandleReturnValue(Dart_NativeArguments args,
- Dart_WeakPersistentHandle rval);
- DART_EXPORT void Dart_SetBooleanReturnValue(Dart_NativeArguments args,
- bool retval);
- DART_EXPORT void Dart_SetIntegerReturnValue(Dart_NativeArguments args,
- int64_t retval);
- DART_EXPORT void Dart_SetDoubleReturnValue(Dart_NativeArguments args,
- double retval);
- /**
- * A native function.
- */
- typedef void (*Dart_NativeFunction)(Dart_NativeArguments arguments);
- /**
- * Native entry resolution callback.
- *
- * For libraries and scripts which have native functions, the embedder
- * can provide a native entry resolver. This callback is used to map a
- * name/arity to a Dart_NativeFunction. If no function is found, the
- * callback should return NULL.
- *
- * The parameters to the native resolver function are:
- * \param name a Dart string which is the name of the native function.
- * \param num_of_arguments is the number of arguments expected by the
- * native function.
- * \param auto_setup_scope is a boolean flag that can be set by the resolver
- * to indicate if this function needs a Dart API scope (see Dart_EnterScope/
- * Dart_ExitScope) to be setup automatically by the VM before calling into
- * the native function. By default most native functions would require this
- * to be true but some light weight native functions which do not call back
- * into the VM through the Dart API may not require a Dart scope to be
- * setup automatically.
- *
- * \return A valid Dart_NativeFunction which resolves to a native entry point
- * for the native function.
- *
- * See Dart_SetNativeResolver.
- */
- typedef Dart_NativeFunction (*Dart_NativeEntryResolver)(Dart_Handle name,
- int num_of_arguments,
- bool* auto_setup_scope);
- /* TODO(turnidge): Consider renaming to NativeFunctionResolver or
- * NativeResolver. */
- /**
- * Native entry symbol lookup callback.
- *
- * For libraries and scripts which have native functions, the embedder
- * can provide a callback for mapping a native entry to a symbol. This callback
- * maps a native function entry PC to the native function name. If no native
- * entry symbol can be found, the callback should return NULL.
- *
- * The parameters to the native reverse resolver function are:
- * \param nf A Dart_NativeFunction.
- *
- * \return A const UTF-8 string containing the symbol name or NULL.
- *
- * See Dart_SetNativeResolver.
- */
- typedef const uint8_t* (*Dart_NativeEntrySymbol)(Dart_NativeFunction nf);
- /**
- * FFI Native C function pointer resolver callback.
- *
- * See Dart_SetFfiNativeResolver.
- */
- typedef void* (*Dart_FfiNativeResolver)(const char* name, uintptr_t args_n);
- /*
- * ===========
- * Environment
- * ===========
- */
- /**
- * An environment lookup callback function.
- *
- * \param name The name of the value to lookup in the environment.
- *
- * \return A valid handle to a string if the name exists in the
- * current environment or Dart_Null() if not.
- */
- typedef Dart_Handle (*Dart_EnvironmentCallback)(Dart_Handle name);
- /**
- * Sets the environment callback for the current isolate. This
- * callback is used to lookup environment values by name in the
- * current environment. This enables the embedder to supply values for
- * the const constructors bool.fromEnvironment, int.fromEnvironment
- * and String.fromEnvironment.
- */
- DART_EXPORT Dart_Handle
- Dart_SetEnvironmentCallback(Dart_EnvironmentCallback callback);
- /**
- * Sets the callback used to resolve native functions for a library.
- *
- * \param library A library.
- * \param resolver A native entry resolver.
- *
- * \return A valid handle if the native resolver was set successfully.
- */
- DART_EXPORT Dart_Handle
- Dart_SetNativeResolver(Dart_Handle library,
- Dart_NativeEntryResolver resolver,
- Dart_NativeEntrySymbol symbol);
- /* TODO(turnidge): Rename to Dart_LibrarySetNativeResolver? */
- /**
- * Returns the callback used to resolve native functions for a library.
- *
- * \param library A library.
- * \param resolver a pointer to a Dart_NativeEntryResolver
- *
- * \return A valid handle if the library was found.
- */
- DART_EXPORT Dart_Handle
- Dart_GetNativeResolver(Dart_Handle library, Dart_NativeEntryResolver* resolver);
- /**
- * Returns the callback used to resolve native function symbols for a library.
- *
- * \param library A library.
- * \param resolver a pointer to a Dart_NativeEntrySymbol.
- *
- * \return A valid handle if the library was found.
- */
- DART_EXPORT Dart_Handle Dart_GetNativeSymbol(Dart_Handle library,
- Dart_NativeEntrySymbol* resolver);
- /**
- * Sets the callback used to resolve FFI native functions for a library.
- * The resolved functions are expected to be a C function pointer of the
- * correct signature (as specified in the `@FfiNative<NFT>()` function
- * annotation in Dart code).
- *
- * NOTE: This is an experimental feature and might change in the future.
- *
- * \param library A library.
- * \param resolver A native function resolver.
- *
- * \return A valid handle if the native resolver was set successfully.
- */
- DART_EXPORT Dart_Handle
- Dart_SetFfiNativeResolver(Dart_Handle library, Dart_FfiNativeResolver resolver);
- /*
- * =====================
- * Scripts and Libraries
- * =====================
- */
- typedef enum {
- Dart_kCanonicalizeUrl = 0,
- Dart_kImportTag,
- Dart_kKernelTag,
- } Dart_LibraryTag;
- /**
- * The library tag handler is a multi-purpose callback provided by the
- * embedder to the Dart VM. The embedder implements the tag handler to
- * provide the ability to load Dart scripts and imports.
- *
- * -- TAGS --
- *
- * Dart_kCanonicalizeUrl
- *
- * This tag indicates that the embedder should canonicalize 'url' with
- * respect to 'library'. For most embedders, the
- * Dart_DefaultCanonicalizeUrl function is a sufficient implementation
- * of this tag. The return value should be a string holding the
- * canonicalized url.
- *
- * Dart_kImportTag
- *
- * This tag is used to load a library from IsolateMirror.loadUri. The embedder
- * should call Dart_LoadLibraryFromKernel to provide the library to the VM. The
- * return value should be an error or library (the result from
- * Dart_LoadLibraryFromKernel).
- *
- * Dart_kKernelTag
- *
- * This tag is used to load the intermediate file (kernel) generated by
- * the Dart front end. This tag is typically used when a 'hot-reload'
- * of an application is needed and the VM is 'use dart front end' mode.
- * The dart front end typically compiles all the scripts, imports and part
- * files into one intermediate file hence we don't use the source/import or
- * script tags. The return value should be an error or a TypedData containing
- * the kernel bytes.
- *
- */
- typedef Dart_Handle (*Dart_LibraryTagHandler)(
- Dart_LibraryTag tag,
- Dart_Handle library_or_package_map_url,
- Dart_Handle url);
- /**
- * Sets library tag handler for the current isolate. This handler is
- * used to handle the various tags encountered while loading libraries
- * or scripts in the isolate.
- *
- * \param handler Handler code to be used for handling the various tags
- * encountered while loading libraries or scripts in the isolate.
- *
- * \return If no error occurs, the handler is set for the isolate.
- * Otherwise an error handle is returned.
- *
- * TODO(turnidge): Document.
- */
- DART_EXPORT Dart_Handle
- Dart_SetLibraryTagHandler(Dart_LibraryTagHandler handler);
- /**
- * Handles deferred loading requests. When this handler is invoked, it should
- * eventually load the deferred loading unit with the given id and call
- * Dart_DeferredLoadComplete or Dart_DeferredLoadCompleteError. It is
- * recommended that the loading occur asynchronously, but it is permitted to
- * call Dart_DeferredLoadComplete or Dart_DeferredLoadCompleteError before the
- * handler returns.
- *
- * If an error is returned, it will be propagated through
- * `prefix.loadLibrary()`. This is useful for synchronous
- * implementations, which must propagate any unwind errors from
- * Dart_DeferredLoadComplete or Dart_DeferredLoadComplete. Otherwise the handler
- * should return a non-error such as `Dart_Null()`.
- */
- typedef Dart_Handle (*Dart_DeferredLoadHandler)(intptr_t loading_unit_id);
- /**
- * Sets the deferred load handler for the current isolate. This handler is
- * used to handle loading deferred imports in an AppJIT or AppAOT program.
- */
- DART_EXPORT Dart_Handle
- Dart_SetDeferredLoadHandler(Dart_DeferredLoadHandler handler);
- /**
- * Notifies the VM that a deferred load completed successfully. This function
- * will eventually cause the corresponding `prefix.loadLibrary()` futures to
- * complete.
- *
- * Requires the current isolate to be the same current isolate during the
- * invocation of the Dart_DeferredLoadHandler.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_DeferredLoadComplete(intptr_t loading_unit_id,
- const uint8_t* snapshot_data,
- const uint8_t* snapshot_instructions);
- /**
- * Notifies the VM that a deferred load failed. This function
- * will eventually cause the corresponding `prefix.loadLibrary()` futures to
- * complete with an error.
- *
- * If `transient` is true, future invocations of `prefix.loadLibrary()` will
- * trigger new load requests. If false, futures invocation will complete with
- * the same error.
- *
- * Requires the current isolate to be the same current isolate during the
- * invocation of the Dart_DeferredLoadHandler.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_DeferredLoadCompleteError(intptr_t loading_unit_id,
- const char* error_message,
- bool transient);
- /**
- * Canonicalizes a url with respect to some library.
- *
- * The url is resolved with respect to the library's url and some url
- * normalizations are performed.
- *
- * This canonicalization function should be sufficient for most
- * embedders to implement the Dart_kCanonicalizeUrl tag.
- *
- * \param base_url The base url relative to which the url is
- * being resolved.
- * \param url The url being resolved and canonicalized. This
- * parameter is a string handle.
- *
- * \return If no error occurs, a String object is returned. Otherwise
- * an error handle is returned.
- */
- DART_EXPORT Dart_Handle Dart_DefaultCanonicalizeUrl(Dart_Handle base_url,
- Dart_Handle url);
- /**
- * Loads the root library for the current isolate.
- *
- * Requires there to be no current root library.
- *
- * \param kernel_buffer A buffer which contains a kernel binary (see
- * pkg/kernel/binary.md). Must remain valid until isolate group shutdown.
- * \param kernel_size Length of the passed in buffer.
- *
- * \return A handle to the root library, or an error.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_LoadScriptFromKernel(const uint8_t* kernel_buffer, intptr_t kernel_size);
- /**
- * Gets the library for the root script for the current isolate.
- *
- * If the root script has not yet been set for the current isolate,
- * this function returns Dart_Null(). This function never returns an
- * error handle.
- *
- * \return Returns the root Library for the current isolate or Dart_Null().
- */
- DART_EXPORT Dart_Handle Dart_RootLibrary(void);
- /**
- * Sets the root library for the current isolate.
- *
- * \return Returns an error handle if `library` is not a library handle.
- */
- DART_EXPORT Dart_Handle Dart_SetRootLibrary(Dart_Handle library);
- /**
- * Lookup or instantiate a legacy type by name and type arguments from a
- * Library.
- *
- * \param library The library containing the class or interface.
- * \param class_name The class name for the type.
- * \param number_of_type_arguments Number of type arguments.
- * For non parametric types the number of type arguments would be 0.
- * \param type_arguments Pointer to an array of type arguments.
- * For non parametric types a NULL would be passed in for this argument.
- *
- * \return If no error occurs, the type is returned.
- * Otherwise an error handle is returned.
- */
- DART_EXPORT Dart_Handle Dart_GetType(Dart_Handle library,
- Dart_Handle class_name,
- intptr_t number_of_type_arguments,
- Dart_Handle* type_arguments);
- /**
- * Lookup or instantiate a nullable type by name and type arguments from
- * Library.
- *
- * \param library The library containing the class or interface.
- * \param class_name The class name for the type.
- * \param number_of_type_arguments Number of type arguments.
- * For non parametric types the number of type arguments would be 0.
- * \param type_arguments Pointer to an array of type arguments.
- * For non parametric types a NULL would be passed in for this argument.
- *
- * \return If no error occurs, the type is returned.
- * Otherwise an error handle is returned.
- */
- DART_EXPORT Dart_Handle Dart_GetNullableType(Dart_Handle library,
- Dart_Handle class_name,
- intptr_t number_of_type_arguments,
- Dart_Handle* type_arguments);
- /**
- * Lookup or instantiate a non-nullable type by name and type arguments from
- * Library.
- *
- * \param library The library containing the class or interface.
- * \param class_name The class name for the type.
- * \param number_of_type_arguments Number of type arguments.
- * For non parametric types the number of type arguments would be 0.
- * \param type_arguments Pointer to an array of type arguments.
- * For non parametric types a NULL would be passed in for this argument.
- *
- * \return If no error occurs, the type is returned.
- * Otherwise an error handle is returned.
- */
- DART_EXPORT Dart_Handle
- Dart_GetNonNullableType(Dart_Handle library,
- Dart_Handle class_name,
- intptr_t number_of_type_arguments,
- Dart_Handle* type_arguments);
- /**
- * Creates a nullable version of the provided type.
- *
- * \param type The type to be converted to a nullable type.
- *
- * \return If no error occurs, a nullable type is returned.
- * Otherwise an error handle is returned.
- */
- DART_EXPORT Dart_Handle Dart_TypeToNullableType(Dart_Handle type);
- /**
- * Creates a non-nullable version of the provided type.
- *
- * \param type The type to be converted to a non-nullable type.
- *
- * \return If no error occurs, a non-nullable type is returned.
- * Otherwise an error handle is returned.
- */
- DART_EXPORT Dart_Handle Dart_TypeToNonNullableType(Dart_Handle type);
- /**
- * A type's nullability.
- *
- * \param type A Dart type.
- * \param result An out parameter containing the result of the check. True if
- * the type is of the specified nullability, false otherwise.
- *
- * \return Returns an error handle if type is not of type Type.
- */
- DART_EXPORT Dart_Handle Dart_IsNullableType(Dart_Handle type, bool* result);
- DART_EXPORT Dart_Handle Dart_IsNonNullableType(Dart_Handle type, bool* result);
- DART_EXPORT Dart_Handle Dart_IsLegacyType(Dart_Handle type, bool* result);
- /**
- * Lookup a class or interface by name from a Library.
- *
- * \param library The library containing the class or interface.
- * \param class_name The name of the class or interface.
- *
- * \return If no error occurs, the class or interface is
- * returned. Otherwise an error handle is returned.
- */
- DART_EXPORT Dart_Handle Dart_GetClass(Dart_Handle library,
- Dart_Handle class_name);
- /* TODO(asiva): The above method needs to be removed once all uses
- * of it are removed from the embedder code. */
- /**
- * Returns an import path to a Library, such as "file:///test.dart" or
- * "dart:core".
- */
- DART_EXPORT Dart_Handle Dart_LibraryUrl(Dart_Handle library);
- /**
- * Returns a URL from which a Library was loaded.
- */
- DART_EXPORT Dart_Handle Dart_LibraryResolvedUrl(Dart_Handle library);
- /**
- * \return An array of libraries.
- */
- DART_EXPORT Dart_Handle Dart_GetLoadedLibraries(void);
- DART_EXPORT Dart_Handle Dart_LookupLibrary(Dart_Handle url);
- /* TODO(turnidge): Consider returning Dart_Null() when the library is
- * not found to distinguish that from a true error case. */
- /**
- * Report an loading error for the library.
- *
- * \param library The library that failed to load.
- * \param error The Dart error instance containing the load error.
- *
- * \return If the VM handles the error, the return value is
- * a null handle. If it doesn't handle the error, the error
- * object is returned.
- */
- DART_EXPORT Dart_Handle Dart_LibraryHandleError(Dart_Handle library,
- Dart_Handle error);
- /**
- * Called by the embedder to load a partial program. Does not set the root
- * library.
- *
- * \param kernel_buffer A buffer which contains a kernel binary (see
- * pkg/kernel/binary.md). Must remain valid until isolate shutdown.
- * \param kernel_buffer_size Length of the passed in buffer.
- *
- * \return A handle to the main library of the compilation unit, or an error.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_LoadLibraryFromKernel(const uint8_t* kernel_buffer,
- intptr_t kernel_buffer_size);
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_LoadLibrary(Dart_Handle kernel_buffer);
- /**
- * Indicates that all outstanding load requests have been satisfied.
- * This finalizes all the new classes loaded and optionally completes
- * deferred library futures.
- *
- * Requires there to be a current isolate.
- *
- * \param complete_futures Specify true if all deferred library
- * futures should be completed, false otherwise.
- *
- * \return Success if all classes have been finalized and deferred library
- * futures are completed. Otherwise, returns an error.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_FinalizeLoading(bool complete_futures);
- /*
- * =====
- * Peers
- * =====
- */
- /**
- * The peer field is a lazily allocated field intended for storage of
- * an uncommonly used values. Most instances types can have a peer
- * field allocated. The exceptions are subtypes of Null, num, and
- * bool.
- */
- /**
- * Returns the value of peer field of 'object' in 'peer'.
- *
- * \param object An object.
- * \param peer An out parameter that returns the value of the peer
- * field.
- *
- * \return Returns an error if 'object' is a subtype of Null, num, or
- * bool.
- */
- DART_EXPORT Dart_Handle Dart_GetPeer(Dart_Handle object, void** peer);
- /**
- * Sets the value of the peer field of 'object' to the value of
- * 'peer'.
- *
- * \param object An object.
- * \param peer A value to store in the peer field.
- *
- * \return Returns an error if 'object' is a subtype of Null, num, or
- * bool.
- */
- DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer);
- /*
- * ======
- * Kernel
- * ======
- */
- /**
- * Experimental support for Dart to Kernel parser isolate.
- *
- * TODO(hausner): Document finalized interface.
- *
- */
- // TODO(33433): Remove kernel service from the embedding API.
- typedef enum {
- Dart_KernelCompilationStatus_Unknown = -1,
- Dart_KernelCompilationStatus_Ok = 0,
- Dart_KernelCompilationStatus_Error = 1,
- Dart_KernelCompilationStatus_Crash = 2,
- Dart_KernelCompilationStatus_MsgFailed = 3,
- } Dart_KernelCompilationStatus;
- typedef struct {
- Dart_KernelCompilationStatus status;
- bool null_safety;
- char* error;
- uint8_t* kernel;
- intptr_t kernel_size;
- } Dart_KernelCompilationResult;
- typedef enum {
- Dart_KernelCompilationVerbosityLevel_Error = 0,
- Dart_KernelCompilationVerbosityLevel_Warning,
- Dart_KernelCompilationVerbosityLevel_Info,
- Dart_KernelCompilationVerbosityLevel_All,
- } Dart_KernelCompilationVerbosityLevel;
- DART_EXPORT bool Dart_IsKernelIsolate(Dart_Isolate isolate);
- DART_EXPORT bool Dart_KernelIsolateIsRunning(void);
- DART_EXPORT Dart_Port Dart_KernelPort(void);
- /**
- * Compiles the given `script_uri` to a kernel file.
- *
- * \param platform_kernel A buffer containing the kernel of the platform (e.g.
- * `vm_platform_strong.dill`). The VM does not take ownership of this memory.
- *
- * \param platform_kernel_size The length of the platform_kernel buffer.
- *
- * \param snapshot_compile Set to `true` when the compilation is for a snapshot.
- * This is used by the frontend to determine if compilation related information
- * should be printed to console (e.g., null safety mode).
- *
- * \param verbosity Specifies the logging behavior of the kernel compilation
- * service.
- *
- * \return Returns the result of the compilation.
- *
- * On a successful compilation the returned [Dart_KernelCompilationResult] has
- * a status of [Dart_KernelCompilationStatus_Ok] and the `kernel`/`kernel_size`
- * fields are set. The caller takes ownership of the malloc()ed buffer.
- *
- * On a failed compilation the `error` might be set describing the reason for
- * the failed compilation. The caller takes ownership of the malloc()ed
- * error.
- *
- * Requires there to be a current isolate.
- */
- DART_EXPORT Dart_KernelCompilationResult
- Dart_CompileToKernel(const char* script_uri,
- const uint8_t* platform_kernel,
- const intptr_t platform_kernel_size,
- bool incremental_compile,
- bool snapshot_compile,
- const char* package_config,
- Dart_KernelCompilationVerbosityLevel verbosity);
- typedef struct {
- const char* uri;
- const char* source;
- } Dart_SourceFile;
- DART_EXPORT Dart_KernelCompilationResult Dart_KernelListDependencies(void);
- /**
- * Sets the kernel buffer which will be used to load Dart SDK sources
- * dynamically at runtime.
- *
- * \param platform_kernel A buffer containing kernel which has sources for the
- * Dart SDK populated. Note: The VM does not take ownership of this memory.
- *
- * \param platform_kernel_size The length of the platform_kernel buffer.
- */
- DART_EXPORT void Dart_SetDartLibrarySourcesKernel(
- const uint8_t* platform_kernel,
- const intptr_t platform_kernel_size);
- /**
- * Detect the null safety opt-in status.
- *
- * When running from source, it is based on the opt-in status of `script_uri`.
- * When running from a kernel buffer, it is based on the mode used when
- * generating `kernel_buffer`.
- * When running from an appJIT or AOT snapshot, it is based on the mode used
- * when generating `snapshot_data`.
- *
- * \param script_uri Uri of the script that contains the source code
- *
- * \param package_config Uri of the package configuration file (either in format
- * of .packages or .dart_tool/package_config.json) for the null safety
- * detection to resolve package imports against. If this parameter is not
- * passed the package resolution of the parent isolate should be used.
- *
- * \param original_working_directory current working directory when the VM
- * process was launched, this is used to correctly resolve the path specified
- * for package_config.
- *
- * \param snapshot_data Buffer containing the snapshot data of the
- * isolate or NULL if no snapshot is provided. If provided, the buffers must
- * remain valid until the isolate shuts down.
- *
- * \param snapshot_instructions Buffer containing the snapshot instructions of
- * the isolate or NULL if no snapshot is provided. If provided, the buffers
- * must remain valid until the isolate shuts down.
- *
- * \param kernel_buffer A buffer which contains a kernel/DIL program. Must
- * remain valid until isolate shutdown.
- *
- * \param kernel_buffer_size The size of `kernel_buffer`.
- *
- * \return Returns true if the null safety is opted in by the input being
- * run `script_uri`, `snapshot_data` or `kernel_buffer`.
- *
- */
- DART_EXPORT bool Dart_DetectNullSafety(const char* script_uri,
- const char* package_config,
- const char* original_working_directory,
- const uint8_t* snapshot_data,
- const uint8_t* snapshot_instructions,
- const uint8_t* kernel_buffer,
- intptr_t kernel_buffer_size);
- #define DART_KERNEL_ISOLATE_NAME "kernel-service"
- /*
- * =======
- * Service
- * =======
- */
- #define DART_VM_SERVICE_ISOLATE_NAME "vm-service"
- /**
- * Returns true if isolate is the service isolate.
- *
- * \param isolate An isolate
- *
- * \return Returns true if 'isolate' is the service isolate.
- */
- DART_EXPORT bool Dart_IsServiceIsolate(Dart_Isolate isolate);
- /**
- * Writes the CPU profile to the timeline as a series of 'instant' events.
- *
- * Note that this is an expensive operation.
- *
- * \param main_port The main port of the Isolate whose profile samples to write.
- * \param error An optional error, must be free()ed by caller.
- *
- * \return Returns true if the profile is successfully written and false
- * otherwise.
- */
- DART_EXPORT bool Dart_WriteProfileToTimeline(Dart_Port main_port, char** error);
- /*
- * ==============
- * Precompilation
- * ==============
- */
- /**
- * Compiles all functions reachable from entry points and marks
- * the isolate to disallow future compilation.
- *
- * Entry points should be specified using `@pragma("vm:entry-point")`
- * annotation.
- *
- * \return An error handle if a compilation error or runtime error running const
- * constructors was encountered.
- */
- DART_EXPORT Dart_Handle Dart_Precompile(void);
- typedef void (*Dart_CreateLoadingUnitCallback)(
- void* callback_data,
- intptr_t loading_unit_id,
- void** write_callback_data,
- void** write_debug_callback_data);
- typedef void (*Dart_StreamingWriteCallback)(void* callback_data,
- const uint8_t* buffer,
- intptr_t size);
- typedef void (*Dart_StreamingCloseCallback)(void* callback_data);
- DART_EXPORT Dart_Handle Dart_LoadingUnitLibraryUris(intptr_t loading_unit_id);
- // On Darwin systems, 'dlsym' adds an '_' to the beginning of the symbol name.
- // Use the '...CSymbol' definitions for resolving through 'dlsym'. The actual
- // symbol names in the objects are given by the '...AsmSymbol' definitions.
- #if defined(__APPLE__)
- #define kSnapshotBuildIdCSymbol "kDartSnapshotBuildId"
- #define kVmSnapshotDataCSymbol "kDartVmSnapshotData"
- #define kVmSnapshotInstructionsCSymbol "kDartVmSnapshotInstructions"
- #define kVmSnapshotBssCSymbol "kDartVmSnapshotBss"
- #define kIsolateSnapshotDataCSymbol "kDartIsolateSnapshotData"
- #define kIsolateSnapshotInstructionsCSymbol "kDartIsolateSnapshotInstructions"
- #define kIsolateSnapshotBssCSymbol "kDartIsolateSnapshotBss"
- #else
- #define kSnapshotBuildIdCSymbol "_kDartSnapshotBuildId"
- #define kVmSnapshotDataCSymbol "_kDartVmSnapshotData"
- #define kVmSnapshotInstructionsCSymbol "_kDartVmSnapshotInstructions"
- #define kVmSnapshotBssCSymbol "_kDartVmSnapshotBss"
- #define kIsolateSnapshotDataCSymbol "_kDartIsolateSnapshotData"
- #define kIsolateSnapshotInstructionsCSymbol "_kDartIsolateSnapshotInstructions"
- #define kIsolateSnapshotBssCSymbol "_kDartIsolateSnapshotBss"
- #endif
- #define kSnapshotBuildIdAsmSymbol "_kDartSnapshotBuildId"
- #define kVmSnapshotDataAsmSymbol "_kDartVmSnapshotData"
- #define kVmSnapshotInstructionsAsmSymbol "_kDartVmSnapshotInstructions"
- #define kVmSnapshotBssAsmSymbol "_kDartVmSnapshotBss"
- #define kIsolateSnapshotDataAsmSymbol "_kDartIsolateSnapshotData"
- #define kIsolateSnapshotInstructionsAsmSymbol \
- "_kDartIsolateSnapshotInstructions"
- #define kIsolateSnapshotBssAsmSymbol "_kDartIsolateSnapshotBss"
- /**
- * Creates a precompiled snapshot.
- * - A root library must have been loaded.
- * - Dart_Precompile must have been called.
- *
- * Outputs an assembly file defining the symbols listed in the definitions
- * above.
- *
- * The assembly should be compiled as a static or shared library and linked or
- * loaded by the embedder. Running this snapshot requires a VM compiled with
- * DART_PRECOMPILED_SNAPSHOT. The kDartVmSnapshotData and
- * kDartVmSnapshotInstructions should be passed to Dart_Initialize. The
- * kDartIsolateSnapshotData and kDartIsolateSnapshotInstructions should be
- * passed to Dart_CreateIsolateGroup.
- *
- * The callback will be invoked one or more times to provide the assembly code.
- *
- * If stripped is true, then the assembly code will not include DWARF
- * debugging sections.
- *
- * If debug_callback_data is provided, debug_callback_data will be used with
- * the callback to provide separate debugging information.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_CreateAppAOTSnapshotAsAssembly(Dart_StreamingWriteCallback callback,
- void* callback_data,
- bool stripped,
- void* debug_callback_data);
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_CreateAppAOTSnapshotAsAssemblies(
- Dart_CreateLoadingUnitCallback next_callback,
- void* next_callback_data,
- bool stripped,
- Dart_StreamingWriteCallback write_callback,
- Dart_StreamingCloseCallback close_callback);
- /**
- * Creates a precompiled snapshot.
- * - A root library must have been loaded.
- * - Dart_Precompile must have been called.
- *
- * Outputs an ELF shared library defining the symbols
- * - _kDartVmSnapshotData
- * - _kDartVmSnapshotInstructions
- * - _kDartIsolateSnapshotData
- * - _kDartIsolateSnapshotInstructions
- *
- * The shared library should be dynamically loaded by the embedder.
- * Running this snapshot requires a VM compiled with DART_PRECOMPILED_SNAPSHOT.
- * The kDartVmSnapshotData and kDartVmSnapshotInstructions should be passed to
- * Dart_Initialize. The kDartIsolateSnapshotData and
- * kDartIsolateSnapshotInstructions should be passed to Dart_CreateIsolate.
- *
- * The callback will be invoked one or more times to provide the binary output.
- *
- * If stripped is true, then the binary output will not include DWARF
- * debugging sections.
- *
- * If debug_callback_data is provided, debug_callback_data will be used with
- * the callback to provide separate debugging information.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_CreateAppAOTSnapshotAsElf(Dart_StreamingWriteCallback callback,
- void* callback_data,
- bool stripped,
- void* debug_callback_data);
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_CreateAppAOTSnapshotAsElfs(Dart_CreateLoadingUnitCallback next_callback,
- void* next_callback_data,
- bool stripped,
- Dart_StreamingWriteCallback write_callback,
- Dart_StreamingCloseCallback close_callback);
- /**
- * Like Dart_CreateAppAOTSnapshotAsAssembly, but only includes
- * kDartVmSnapshotData and kDartVmSnapshotInstructions. It also does
- * not strip DWARF information from the generated assembly or allow for
- * separate debug information.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_CreateVMAOTSnapshotAsAssembly(Dart_StreamingWriteCallback callback,
- void* callback_data);
- /**
- * Sorts the class-ids in depth first traversal order of the inheritance
- * tree. This is a costly operation, but it can make method dispatch
- * more efficient and is done before writing snapshots.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_SortClasses(void);
- /**
- * Creates a snapshot that caches compiled code and type feedback for faster
- * startup and quicker warmup in a subsequent process.
- *
- * Outputs a snapshot in two pieces. The pieces should be passed to
- * Dart_CreateIsolateGroup in a VM using the same VM snapshot pieces used in the
- * current VM. The instructions piece must be loaded with read and execute
- * permissions; the data piece may be loaded as read-only.
- *
- * - Requires the VM to have not been started with --precompilation.
- * - Not supported when targeting IA32.
- * - The VM writing the snapshot and the VM reading the snapshot must be the
- * same version, must be built in the same DEBUG/RELEASE/PRODUCT mode, must
- * be targeting the same architecture, and must both be in checked mode or
- * both in unchecked mode.
- *
- * The buffers are scope allocated and are only valid until the next call to
- * Dart_ExitScope.
- *
- * \return A valid handle if no error occurs during the operation.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_CreateAppJITSnapshotAsBlobs(uint8_t** isolate_snapshot_data_buffer,
- intptr_t* isolate_snapshot_data_size,
- uint8_t** isolate_snapshot_instructions_buffer,
- intptr_t* isolate_snapshot_instructions_size);
- /**
- * Like Dart_CreateAppJITSnapshotAsBlobs, but also creates a new VM snapshot.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_CreateCoreJITSnapshotAsBlobs(
- uint8_t** vm_snapshot_data_buffer,
- intptr_t* vm_snapshot_data_size,
- uint8_t** vm_snapshot_instructions_buffer,
- intptr_t* vm_snapshot_instructions_size,
- uint8_t** isolate_snapshot_data_buffer,
- intptr_t* isolate_snapshot_data_size,
- uint8_t** isolate_snapshot_instructions_buffer,
- intptr_t* isolate_snapshot_instructions_size);
- /**
- * Get obfuscation map for precompiled code.
- *
- * Obfuscation map is encoded as a JSON array of pairs (original name,
- * obfuscated name).
- *
- * \return Returns an error handler if the VM was built in a mode that does not
- * support obfuscation.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle
- Dart_GetObfuscationMap(uint8_t** buffer, intptr_t* buffer_length);
- /**
- * Returns whether the VM only supports running from precompiled snapshots and
- * not from any other kind of snapshot or from source (that is, the VM was
- * compiled with DART_PRECOMPILED_RUNTIME).
- */
- DART_EXPORT bool Dart_IsPrecompiledRuntime(void);
- /**
- * Print a native stack trace. Used for crash handling.
- *
- * If context is NULL, prints the current stack trace. Otherwise, context
- * should be a CONTEXT* (Windows) or ucontext_t* (POSIX) from a signal handler
- * running on the current thread.
- */
- DART_EXPORT void Dart_DumpNativeStackTrace(void* context);
- /**
- * Indicate that the process is about to abort, and the Dart VM should not
- * attempt to cleanup resources.
- */
- DART_EXPORT void Dart_PrepareToAbort(void);
- /**
- * Callback provided by the embedder that is used by the VM to
- * produce footnotes appended to DWARF stack traces.
- *
- * Whenever VM formats a stack trace as a string it would call this callback
- * passing raw program counters for each frame in the stack trace.
- *
- * Embedder can then return a string which if not-null will be appended to the
- * formatted stack trace.
- *
- * Returned string is expected to be `malloc()` allocated. VM takes ownership
- * of the returned string and will `free()` it.
- *
- * \param addresses raw program counter addresses for each frame
- * \param count number of elements in the addresses array
- */
- typedef char* (*Dart_DwarfStackTraceFootnoteCallback)(void* addresses[],
- intptr_t count);
- /**
- * Configure DWARF stack trace footnote callback.
- */
- DART_EXPORT void Dart_SetDwarfStackTraceFootnoteCallback(
- Dart_DwarfStackTraceFootnoteCallback callback);
- #endif /* INCLUDE_DART_API_H_ */ /* NOLINT */
|