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 * Note that Dart_CObject_kNativePointer is intended for internal use by
37 * dart:io implementation and has no connection to dart:ffi Pointer class.
38 * It represents a pointer to a native resource of a known type.
39 * The receiving side will only see this pointer as an integer and will not
40 * see the specified finalizer.
41 * The specified finalizer will only be invoked if the message is not delivered.
42 */
43typedef enum {
44 Dart_CObject_kNull = 0,
45 Dart_CObject_kBool,
46 Dart_CObject_kInt32,
47 Dart_CObject_kInt64,
48 Dart_CObject_kDouble,
49 Dart_CObject_kString,
50 Dart_CObject_kArray,
51 Dart_CObject_kTypedData,
52 Dart_CObject_kExternalTypedData,
53 Dart_CObject_kSendPort,
54 Dart_CObject_kCapability,
55 Dart_CObject_kNativePointer,
56 Dart_CObject_kUnsupported,
57 Dart_CObject_kUnmodifiableExternalTypedData,
58 Dart_CObject_kNumberOfTypes
59} Dart_CObject_Type;
60// This enum is versioned by DART_API_DL_MAJOR_VERSION, only add at the end
61// and bump the DART_API_DL_MINOR_VERSION.
62
63typedef struct _Dart_CObject {
64 Dart_CObject_Type type;
65 union {
66 bool as_bool;
67 int32_t as_int32;
68 int64_t as_int64;
69 double as_double;
70 const char* as_string;
71 struct {
72 Dart_Port id;
73 Dart_Port origin_id;
74 } as_send_port;
75 struct {
76 int64_t id;
77 } as_capability;
78 struct {
79 intptr_t length;
80 struct _Dart_CObject** values;
81 } as_array;
82 struct {
83 Dart_TypedData_Type type;
84 intptr_t length; /* in elements, not bytes */
85 const uint8_t* values;
86 } as_typed_data;
87 struct {
88 Dart_TypedData_Type type;
89 intptr_t length; /* in elements, not bytes */
90 uint8_t* data;
91 void* peer;
92 Dart_HandleFinalizer callback;
93 } as_external_typed_data;
94 struct {
95 intptr_t ptr;
96 intptr_t size;
97 Dart_HandleFinalizer callback;
98 } as_native_pointer;
99 } value;
100} Dart_CObject;
101// This struct is versioned by DART_API_DL_MAJOR_VERSION, bump the version when
102// changing this struct.
103
104/**
105 * Posts a message on some port. The message will contain the Dart_CObject
106 * object graph rooted in 'message'.
107 *
108 * While the message is being sent the state of the graph of Dart_CObject
109 * structures rooted in 'message' should not be accessed, as the message
110 * generation will make temporary modifications to the data. When the message
111 * has been sent the graph will be fully restored.
112 *
113 * If true is returned, the message was enqueued, and finalizers for external
114 * typed data will eventually run, even if the receiving isolate shuts down
115 * before processing the message. If false is returned, the message was not
116 * enqueued and ownership of external typed data in the message remains with the
117 * caller.
118 *
119 * This function may be called on any thread when the VM is running (that is,
120 * after Dart_Initialize has returned and before Dart_Cleanup has been called).
121 *
122 * \param port_id The destination port.
123 * \param message The message to send.
124 *
125 * \return True if the message was posted.
126 */
127DART_EXPORT bool Dart_PostCObject(Dart_Port port_id, Dart_CObject* message);
128
129/**
130 * Posts a message on some port. The message will contain the integer 'message'.
131 *
132 * \param port_id The destination port.
133 * \param message The message to send.
134 *
135 * \return True if the message was posted.
136 */
137DART_EXPORT bool Dart_PostInteger(Dart_Port port_id, int64_t message);
138
139/**
140 * A native message handler.
141 *
142 * This handler is associated with a native port by calling
143 * Dart_NewNativePort.
144 *
145 * The message received is decoded into the message structure. The
146 * lifetime of the message data is controlled by the caller. All the
147 * data references from the message are allocated by the caller and
148 * will be reclaimed when returning to it.
149 */
150typedef void (*Dart_NativeMessageHandler)(Dart_Port dest_port_id,
151 Dart_CObject* message);
152
153/**
154 * Creates a new native port. When messages are received on this
155 * native port, then they will be dispatched to the provided native
156 * message handler.
157 *
158 * \param name The name of this port in debugging messages.
159 * \param handler The C handler to run when messages arrive on the port.
160 * \param handle_concurrently Is it okay to process requests on this
161 * native port concurrently?
162 *
163 * \return If successful, returns the port id for the native port. In
164 * case of error, returns ILLEGAL_PORT.
165 */
166DART_EXPORT Dart_Port Dart_NewNativePort(const char* name,
167 Dart_NativeMessageHandler handler,
168 bool handle_concurrently);
169/* TODO(turnidge): Currently handle_concurrently is ignored. */
170
171/**
172 * Closes the native port with the given id.
173 *
174 * The port must have been allocated by a call to Dart_NewNativePort.
175 *
176 * \param native_port_id The id of the native port to close.
177 *
178 * \return Returns true if the port was closed successfully.
179 */
180DART_EXPORT bool Dart_CloseNativePort(Dart_Port native_port_id);
181
182/*
183 * ==================
184 * Verification Tools
185 * ==================
186 */
187
188/**
189 * Forces all loaded classes and functions to be compiled eagerly in
190 * the current isolate..
191 *
192 * TODO(turnidge): Document.
193 */
194DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_CompileAll(void);
195
196/**
197 * Finalizes all classes.
198 */
199DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_FinalizeAllClasses(void);
200
201/* This function is intentionally undocumented.
202 *
203 * It should not be used outside internal tests.
204 */
205DART_EXPORT void* Dart_ExecuteInternalCommand(const char* command, void* arg);
206
207#endif /* INCLUDE_DART_NATIVE_API_H_ */ /* NOLINT */
208

source code of dart_sdk/runtime/include/dart_native_api.h