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