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