dart_native_api.h 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207
  1. /*
  2. * Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file
  3. * for details. All rights reserved. Use of this source code is governed by a
  4. * BSD-style license that can be found in the LICENSE file.
  5. */
  6. #ifndef RUNTIME_INCLUDE_DART_NATIVE_API_H_
  7. #define RUNTIME_INCLUDE_DART_NATIVE_API_H_
  8. #include "dart_api.h" /* NOLINT */
  9. /*
  10. * ==========================================
  11. * Message sending/receiving from native code
  12. * ==========================================
  13. */
  14. /**
  15. * A Dart_CObject is used for representing Dart objects as native C
  16. * data outside the Dart heap. These objects are totally detached from
  17. * the Dart heap. Only a subset of the Dart objects have a
  18. * representation as a Dart_CObject.
  19. *
  20. * The string encoding in the 'value.as_string' is UTF-8.
  21. *
  22. * All the different types from dart:typed_data are exposed as type
  23. * kTypedData. The specific type from dart:typed_data is in the type
  24. * field of the as_typed_data structure. The length in the
  25. * as_typed_data structure is always in bytes.
  26. *
  27. * The data for kTypedData is copied on message send and ownership remains with
  28. * the caller. The ownership of data for kExternalTyped is passed to the VM on
  29. * message send and returned when the VM invokes the
  30. * Dart_HandleFinalizer callback; a non-NULL callback must be provided.
  31. *
  32. * Note that Dart_CObject_kNativePointer is intended for internal use by
  33. * dart:io implementation and has no connection to dart:ffi Pointer class.
  34. * It represents a pointer to a native resource of a known type.
  35. * The receiving side will only see this pointer as an integer and will not
  36. * see the specified finalizer.
  37. * The specified finalizer will only be invoked if the message is not delivered.
  38. */
  39. typedef enum {
  40. Dart_CObject_kNull = 0,
  41. Dart_CObject_kBool,
  42. Dart_CObject_kInt32,
  43. Dart_CObject_kInt64,
  44. Dart_CObject_kDouble,
  45. Dart_CObject_kString,
  46. Dart_CObject_kArray,
  47. Dart_CObject_kTypedData,
  48. Dart_CObject_kExternalTypedData,
  49. Dart_CObject_kSendPort,
  50. Dart_CObject_kCapability,
  51. Dart_CObject_kNativePointer,
  52. Dart_CObject_kUnsupported,
  53. Dart_CObject_kUnmodifiableExternalTypedData,
  54. Dart_CObject_kNumberOfTypes
  55. } Dart_CObject_Type;
  56. // This enum is versioned by DART_API_DL_MAJOR_VERSION, only add at the end
  57. // and bump the DART_API_DL_MINOR_VERSION.
  58. typedef struct _Dart_CObject {
  59. Dart_CObject_Type type;
  60. union {
  61. bool as_bool;
  62. int32_t as_int32;
  63. int64_t as_int64;
  64. double as_double;
  65. const char* as_string;
  66. struct {
  67. Dart_Port id;
  68. Dart_Port origin_id;
  69. } as_send_port;
  70. struct {
  71. int64_t id;
  72. } as_capability;
  73. struct {
  74. intptr_t length;
  75. struct _Dart_CObject** values;
  76. } as_array;
  77. struct {
  78. Dart_TypedData_Type type;
  79. intptr_t length; /* in elements, not bytes */
  80. const uint8_t* values;
  81. } as_typed_data;
  82. struct {
  83. Dart_TypedData_Type type;
  84. intptr_t length; /* in elements, not bytes */
  85. uint8_t* data;
  86. void* peer;
  87. Dart_HandleFinalizer callback;
  88. } as_external_typed_data;
  89. struct {
  90. intptr_t ptr;
  91. intptr_t size;
  92. Dart_HandleFinalizer callback;
  93. } as_native_pointer;
  94. } value;
  95. } Dart_CObject;
  96. // This struct is versioned by DART_API_DL_MAJOR_VERSION, bump the version when
  97. // changing this struct.
  98. /**
  99. * Posts a message on some port. The message will contain the Dart_CObject
  100. * object graph rooted in 'message'.
  101. *
  102. * While the message is being sent the state of the graph of Dart_CObject
  103. * structures rooted in 'message' should not be accessed, as the message
  104. * generation will make temporary modifications to the data. When the message
  105. * has been sent the graph will be fully restored.
  106. *
  107. * If true is returned, the message was enqueued, and finalizers for external
  108. * typed data will eventually run, even if the receiving isolate shuts down
  109. * before processing the message. If false is returned, the message was not
  110. * enqueued and ownership of external typed data in the message remains with the
  111. * caller.
  112. *
  113. * This function may be called on any thread when the VM is running (that is,
  114. * after Dart_Initialize has returned and before Dart_Cleanup has been called).
  115. *
  116. * \param port_id The destination port.
  117. * \param message The message to send.
  118. *
  119. * \return True if the message was posted.
  120. */
  121. DART_EXPORT bool Dart_PostCObject(Dart_Port port_id, Dart_CObject* message);
  122. /**
  123. * Posts a message on some port. The message will contain the integer 'message'.
  124. *
  125. * \param port_id The destination port.
  126. * \param message The message to send.
  127. *
  128. * \return True if the message was posted.
  129. */
  130. DART_EXPORT bool Dart_PostInteger(Dart_Port port_id, int64_t message);
  131. /**
  132. * A native message handler.
  133. *
  134. * This handler is associated with a native port by calling
  135. * Dart_NewNativePort.
  136. *
  137. * The message received is decoded into the message structure. The
  138. * lifetime of the message data is controlled by the caller. All the
  139. * data references from the message are allocated by the caller and
  140. * will be reclaimed when returning to it.
  141. */
  142. typedef void (*Dart_NativeMessageHandler)(Dart_Port dest_port_id,
  143. Dart_CObject* message);
  144. /**
  145. * Creates a new native port. When messages are received on this
  146. * native port, then they will be dispatched to the provided native
  147. * message handler.
  148. *
  149. * \param name The name of this port in debugging messages.
  150. * \param handler The C handler to run when messages arrive on the port.
  151. * \param handle_concurrently Is it okay to process requests on this
  152. * native port concurrently?
  153. *
  154. * \return If successful, returns the port id for the native port. In
  155. * case of error, returns ILLEGAL_PORT.
  156. */
  157. DART_EXPORT Dart_Port Dart_NewNativePort(const char* name,
  158. Dart_NativeMessageHandler handler,
  159. bool handle_concurrently);
  160. /* TODO(turnidge): Currently handle_concurrently is ignored. */
  161. /**
  162. * Closes the native port with the given id.
  163. *
  164. * The port must have been allocated by a call to Dart_NewNativePort.
  165. *
  166. * \param native_port_id The id of the native port to close.
  167. *
  168. * \return Returns true if the port was closed successfully.
  169. */
  170. DART_EXPORT bool Dart_CloseNativePort(Dart_Port native_port_id);
  171. /*
  172. * ==================
  173. * Verification Tools
  174. * ==================
  175. */
  176. /**
  177. * Forces all loaded classes and functions to be compiled eagerly in
  178. * the current isolate..
  179. *
  180. * TODO(turnidge): Document.
  181. */
  182. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_CompileAll(void);
  183. /**
  184. * Finalizes all classes.
  185. */
  186. DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_FinalizeAllClasses(void);
  187. /* This function is intentionally undocumented.
  188. *
  189. * It should not be used outside internal tests.
  190. */
  191. DART_EXPORT void* Dart_ExecuteInternalCommand(const char* command, void* arg);
  192. #endif /* INCLUDE_DART_NATIVE_API_H_ */ /* NOLINT */