1 | /* Copyright JS Foundation and other contributors, http://js.foundation |
2 | * |
3 | * Licensed under the Apache License, Version 2.0 (the "License"); |
4 | * you may not use this file except in compliance with the License. |
5 | * You may obtain a copy of the License at |
6 | * |
7 | * http://www.apache.org/licenses/LICENSE-2.0 |
8 | * |
9 | * Unless required by applicable law or agreed to in writing, software |
10 | * distributed under the License is distributed on an "AS IS" BASIS |
11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
12 | * See the License for the specific language governing permissions and |
13 | * limitations under the License. |
14 | */ |
15 | |
16 | #ifndef JERRYSCRIPT_PORT_H |
17 | #define JERRYSCRIPT_PORT_H |
18 | |
19 | #include <stdbool.h> |
20 | #include <stdint.h> |
21 | #include <stdio.h> |
22 | |
23 | #include "jerryscript-compiler.h" |
24 | #include "jerryscript-core.h" |
25 | |
26 | #ifdef __cplusplus |
27 | extern "C" |
28 | { |
29 | #endif /* __cplusplus */ |
30 | |
31 | /** \addtogroup jerry_port Jerry engine port |
32 | * @{ |
33 | */ |
34 | |
35 | /* |
36 | * Termination Port API |
37 | * |
38 | * Note: |
39 | * It is questionable whether a library should be able to terminate an |
40 | * application. However, as of now, we only have the concept of completion |
41 | * code around jerry_parse and jerry_run. Most of the other API functions |
42 | * have no way of signaling an error. So, we keep the termination approach |
43 | * with this port function. |
44 | */ |
45 | |
46 | /** |
47 | * Error codes |
48 | */ |
49 | typedef enum |
50 | { |
51 | ERR_OUT_OF_MEMORY = 10, |
52 | ERR_REF_COUNT_LIMIT = 12, |
53 | ERR_DISABLED_BYTE_CODE = 13, |
54 | ERR_UNTERMINATED_GC_LOOPS = 14, |
55 | ERR_FAILED_INTERNAL_ASSERTION = 120 |
56 | } jerry_fatal_code_t; |
57 | |
58 | /** |
59 | * Signal the port that jerry experienced a fatal failure from which it cannot |
60 | * recover. |
61 | * |
62 | * @param code gives the cause of the error. |
63 | * |
64 | * Note: |
65 | * Jerry expects the function not to return. |
66 | * |
67 | * Example: a libc-based port may implement this with exit() or abort(), or both. |
68 | */ |
69 | void JERRY_ATTR_NORETURN jerry_port_fatal (jerry_fatal_code_t code); |
70 | |
71 | /* |
72 | * I/O Port API |
73 | */ |
74 | |
75 | /** |
76 | * Jerry log levels. The levels are in severity order |
77 | * where the most serious levels come first. |
78 | */ |
79 | typedef enum |
80 | { |
81 | JERRY_LOG_LEVEL_ERROR, /**< the engine will terminate after the message is printed */ |
82 | JERRY_LOG_LEVEL_WARNING, /**< a request is aborted, but the engine continues its operation */ |
83 | JERRY_LOG_LEVEL_DEBUG, /**< debug messages from the engine, low volume */ |
84 | JERRY_LOG_LEVEL_TRACE /**< detailed info about engine internals, potentially high volume */ |
85 | } jerry_log_level_t; |
86 | |
87 | /** |
88 | * Display or log a debug/error message. The function should implement a printf-like |
89 | * interface, where the first argument specifies the log level |
90 | * and the second argument specifies a format string on how to stringify the rest |
91 | * of the parameter list. |
92 | * |
93 | * This function is only called with messages coming from the jerry engine as |
94 | * the result of some abnormal operation or describing its internal operations |
95 | * (e.g., data structure dumps or tracing info). |
96 | * |
97 | * It should be the port that decides whether error and debug messages are logged to |
98 | * the console, or saved to a database or to a file. |
99 | * |
100 | * Example: a libc-based port may implement this with vfprintf(stderr) or |
101 | * vfprintf(logfile), or both, depending on log level. |
102 | * |
103 | * Note: |
104 | * This port function is called by jerry-core when JERRY_LOGGING is |
105 | * enabled. It is also common practice though to use this function in |
106 | * application code. |
107 | */ |
108 | void JERRY_ATTR_FORMAT (printf, 2, 3) jerry_port_log (jerry_log_level_t level, const char *format, ...); |
109 | |
110 | /* |
111 | * Date Port API |
112 | */ |
113 | |
114 | /** |
115 | * Get local time zone adjustment, in milliseconds, for the given timestamp. |
116 | * The timestamp can be specified in either UTC or local time, depending on |
117 | * the value of is_utc. Adding the value returned from this function to |
118 | * a timestamp in UTC time should result in local time for the current time |
119 | * zone, and subtracting it from a timestamp in local time should result in |
120 | * UTC time. |
121 | * |
122 | * Ideally, this function should satisfy the stipulations applied to LocalTZA |
123 | * in section 20.3.1.7 of the ECMAScript version 9.0 spec. |
124 | * |
125 | * See Also: |
126 | * ECMA-262 v9, 20.3.1.7 |
127 | * |
128 | * Note: |
129 | * This port function is called by jerry-core when |
130 | * JERRY_BUILTIN_DATE is defined to 1. Otherwise this function is |
131 | * not used. |
132 | * |
133 | * @param unix_ms The unix timestamp we want an offset for, given in |
134 | * millisecond precision (could be now, in the future, |
135 | * or in the past). As with all unix timestamps, 0 refers to |
136 | * 1970-01-01, a day is exactly 86 400 000 milliseconds, and |
137 | * leap seconds cause the same second to occur twice. |
138 | * @param is_utc Is the given timestamp in UTC time? If false, it is in local |
139 | * time. |
140 | * |
141 | * @return milliseconds between local time and UTC for the given timestamp, |
142 | * if available |
143 | *. 0 if not available / we are in UTC. |
144 | */ |
145 | double jerry_port_get_local_time_zone_adjustment (double unix_ms, bool is_utc); |
146 | |
147 | /** |
148 | * Get system time |
149 | * |
150 | * Note: |
151 | * This port function is called by jerry-core when |
152 | * JERRY_BUILTIN_DATE is defined to 1. It is also common practice |
153 | * in application code to use this function for the initialization of the |
154 | * random number generator. |
155 | * |
156 | * @return milliseconds since Unix epoch |
157 | */ |
158 | double jerry_port_get_current_time (void); |
159 | |
160 | /** |
161 | * Get the current context of the engine. Each port should provide its own |
162 | * implementation of this interface. |
163 | * |
164 | * Note: |
165 | * This port function is called by jerry-core when |
166 | * JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not |
167 | * used. |
168 | * |
169 | * @return the pointer to the engine context. |
170 | */ |
171 | struct jerry_context_t *jerry_port_get_current_context (void); |
172 | |
173 | /** |
174 | * Makes the process sleep for a given time. |
175 | * |
176 | * Note: |
177 | * This port function is called by jerry-core when JERRY_DEBUGGER is |
178 | * enabled (set to 1). Otherwise this function is not used. |
179 | * |
180 | * @param sleep_time milliseconds to sleep. |
181 | */ |
182 | void jerry_port_sleep (uint32_t sleep_time); |
183 | |
184 | /** |
185 | * Print a single character. |
186 | * |
187 | * Note: |
188 | * This port function is here so the jerry-ext components would have |
189 | * a common way to print out information. |
190 | * If possible do not use from the jerry-core. |
191 | * |
192 | * @param c the character to print. |
193 | */ |
194 | void jerry_port_print_char (char c); |
195 | |
196 | /** |
197 | * Open a source file and read its contents into a buffer. |
198 | * |
199 | * Note: |
200 | * This port function is called by jerry-core when JERRY_MODULE_SYSTEM |
201 | * is enabled. The path is specified in the import statement's 'from "..."' |
202 | * section. |
203 | * |
204 | * @param file_name_p Path that points to the EcmaScript file in the |
205 | * filesystem. |
206 | * @param out_size_p The opened file's size in bytes. |
207 | * |
208 | * @return the pointer to the buffer which contains the content of the file. |
209 | */ |
210 | uint8_t *jerry_port_read_source (const char *file_name_p, size_t *out_size_p); |
211 | |
212 | /** |
213 | * Frees the allocated buffer after the contents of the file are not needed |
214 | * anymore. |
215 | * |
216 | * @param buffer_p The pointer the allocated buffer. |
217 | */ |
218 | void jerry_port_release_source (uint8_t *buffer_p); |
219 | |
220 | /** |
221 | * Normalize a file path string. |
222 | * |
223 | * Note: |
224 | * This port function is called by jerry-core when JERRY_MODULE_SYSTEM |
225 | * is enabled. The normalized path is used to uniquely identify modules. |
226 | * |
227 | * @param in_path_p Input path as a zero terminated string. |
228 | * @param out_buf_p Pointer to the output buffer where the normalized path should be written. |
229 | * @param out_buf_size Size of the output buffer. |
230 | * @param base_file_p A file path that 'in_path_p' is relative to, usually the current module file. |
231 | * A NULL value represents that 'in_path_p' is relative to the current working directory. |
232 | * |
233 | * @return length of the string written to the output buffer |
234 | * zero, if the buffer was not sufficient or an error occured |
235 | */ |
236 | size_t jerry_port_normalize_path (const char *in_path_p, |
237 | char *out_buf_p, |
238 | size_t out_buf_size, |
239 | char *base_file_p); |
240 | |
241 | /** |
242 | * Get the module object of a native module. |
243 | * |
244 | * Note: |
245 | * This port function is called by jerry-core when JERRY_MODULE_SYSTEM |
246 | * is enabled. |
247 | * |
248 | * @param name String value of the module specifier. |
249 | * |
250 | * @return Undefined, if 'name' is not a native module |
251 | * jerry_value_t containing the module object, otherwise |
252 | */ |
253 | jerry_value_t jerry_port_get_native_module (jerry_value_t name); |
254 | |
255 | /** |
256 | * HostPromiseRejectionTracker operations |
257 | */ |
258 | typedef enum |
259 | { |
260 | JERRY_PROMISE_REJECTION_OPERATION_REJECT, /**< promise is rejected without any handlers */ |
261 | JERRY_PROMISE_REJECTION_OPERATION_HANDLE, /**< handler is added to a rejected promise for the first time */ |
262 | } jerry_promise_rejection_operation_t; |
263 | |
264 | /** |
265 | * Track unhandled promise rejections. |
266 | * |
267 | * Note: |
268 | * This port function is called by jerry-core when JERRY_BUILTIN_PROMISE |
269 | * is enabled. |
270 | * |
271 | * @param promise rejected promise |
272 | * @param operation HostPromiseRejectionTracker operation |
273 | */ |
274 | void jerry_port_track_promise_rejection (const jerry_value_t promise, |
275 | const jerry_promise_rejection_operation_t operation); |
276 | |
277 | /** |
278 | * @} |
279 | */ |
280 | |
281 | #ifdef __cplusplus |
282 | } |
283 | #endif /* __cplusplus */ |
284 | #endif /* !JERRYSCRIPT_PORT_H */ |
285 | |