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 JERRYX_HANDLE_SCOPE_H
17#define JERRYX_HANDLE_SCOPE_H
18
19#include "jerryscript.h"
20
21#ifdef __cplusplus
22extern "C"
23{
24#endif /* __cplusplus */
25
26#ifndef JERRYX_HANDLE_PRELIST_SIZE
27#define JERRYX_HANDLE_PRELIST_SIZE 20
28#endif
29
30#ifndef JERRYX_SCOPE_PRELIST_SIZE
31#define JERRYX_SCOPE_PRELIST_SIZE 20
32#endif
33
34#define STATIC_ASSERT(COND,MSG) typedef char static_assertion_##MSG[(COND)?1:-1]
35
36STATIC_ASSERT (JERRYX_SCOPE_PRELIST_SIZE < 32, JERRYX_SCOPE_PRELIST_SIZE_must_be_less_than_size_of_uint8_t);
37
38#undef STATIC_ASSERT
39
40typedef struct jerryx_handle_t jerryx_handle_t;
41/**
42 * Dynamically allocated handle in the scopes.
43 * Scopes has it's own size-limited linear storage of handles. Still there
44 * might be not enough space left for new handles, dynamically allocated
45 * `jerryx_handle_t` could ease the pre-allocated linear memory burden.
46 */
47struct jerryx_handle_t
48{
49  jerry_value_t jval; /**< jerry value of the handle bound to */
50  jerryx_handle_t *sibling; /**< next sibling the the handle */
51};
52
53#define JERRYX_HANDLE_SCOPE_FIELDS                          \
54  jerry_value_t handle_prelist[JERRYX_HANDLE_PRELIST_SIZE]; \
55  uint8_t prelist_handle_count;                             \
56  bool escaped;                                             \
57  jerryx_handle_t *handle_ptr
58
59typedef struct jerryx_handle_scope_s jerryx_handle_scope_t;
60typedef jerryx_handle_scope_t *jerryx_handle_scope;
61typedef jerryx_handle_scope_t *jerryx_escapable_handle_scope;
62/**
63 * Inlined simple handle scope type.
64 */
65struct jerryx_handle_scope_s
66{
67  JERRYX_HANDLE_SCOPE_FIELDS; /**< common handle scope fields */
68};
69
70typedef struct jerryx_handle_scope_dynamic_s jerryx_handle_scope_dynamic_t;
71/**
72 * Dynamically allocated handle scope type.
73 */
74struct jerryx_handle_scope_dynamic_s
75{
76  JERRYX_HANDLE_SCOPE_FIELDS; /**< common handle scope fields */
77  jerryx_handle_scope_dynamic_t *child; /**< child dynamically allocated handle scope */
78  jerryx_handle_scope_dynamic_t *parent; /**< parent dynamically allocated handle scope */
79};
80
81#undef JERRYX_HANDLE_SCOPE_FIELDS
82
83typedef enum
84{
85  jerryx_handle_scope_ok = 0,
86
87  jerryx_escape_called_twice,
88  jerryx_handle_scope_mismatch,
89} jerryx_handle_scope_status;
90
91jerryx_handle_scope_status
92jerryx_open_handle_scope (jerryx_handle_scope *result);
93
94jerryx_handle_scope_status
95jerryx_close_handle_scope (jerryx_handle_scope scope);
96
97jerryx_handle_scope_status
98jerryx_open_escapable_handle_scope (jerryx_handle_scope *result);
99
100jerryx_handle_scope_status
101jerryx_close_escapable_handle_scope (jerryx_handle_scope scope);
102
103jerryx_handle_scope_status
104jerryx_escape_handle (jerryx_escapable_handle_scope scope,
105                      jerry_value_t escapee,
106                      jerry_value_t *result);
107
108/**
109 * Completely escape a handle from handle scope,
110 * leave life time management totally up to user.
111 */
112jerryx_handle_scope_status
113jerryx_remove_handle (jerryx_escapable_handle_scope scope,
114                      jerry_value_t escapee,
115                      jerry_value_t *result);
116
117jerry_value_t
118jerryx_create_handle (jerry_value_t jval);
119
120jerry_value_t
121jerryx_create_handle_in_scope (jerry_value_t jval, jerryx_handle_scope scope);
122
123/** MARK: - handle-scope-allocator.c */
124jerryx_handle_scope_t *
125jerryx_handle_scope_get_current (void);
126
127jerryx_handle_scope_t *
128jerryx_handle_scope_get_root (void);
129/** MARK: - END handle-scope-allocator.c */
130
131#ifdef __cplusplus
132}
133#endif /* __cplusplus */
134#endif /* !JERRYX_HANDLE_SCOPE_H */
135