xs/XSBind.h

filter: Statementstmt 100% 2 / 2 Branchbran 100% 2 / 2 Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 100% 4 / 4 CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« blib/lib/Clownfish/Vector.pm ↑ Summary
1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements. See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16  
17 /* XSBind.h -- Functions to help bind Clownfish to Perl XS api.
18 */
19  
20 #ifndef H_CFISH_XSBIND
21 #define H_CFISH_XSBIND 1
22  
23 #include "Clownfish/Obj.h"
24 #include "Clownfish/Blob.h"
25 #include "Clownfish/ByteBuf.h"
26 #include "Clownfish/String.h"
27 #include "Clownfish/Err.h"
28 #include "Clownfish/Hash.h"
29 #include "Clownfish/Num.h"
30 #include "Clownfish/Vector.h"
31 #include "Clownfish/Class.h"
32  
33 /* Avoid conflicts with Clownfish bool type. */
34 #define HAS_BOOL
35 #define PERL_NO_GET_CONTEXT
36 #include "EXTERN.h"
37 #include "perl.h"
38 #include "XSUB.h"
39  
40 #define NEED_newRV_noinc_GLOBAL
41 #include "ppport.h"
42  
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46  
47 typedef struct cfish_XSBind_ClassSpec {
48 const char *name;
49 const char *parent_name;
50 uint32_t num_methods;
51 } cfish_XSBind_ClassSpec;
52  
53 typedef struct cfish_XSBind_XSubSpec {
54 const char *alias;
55 XSUBADDR_t xsub;
56 } cfish_XSBind_XSubSpec;
57  
58 typedef struct cfish_XSBind_ParamSpec {
59 const char *label;
60 uint16_t label_len;
61 char required;
62 } cfish_XSBind_ParamSpec;
63  
64 /** Given either a class name or a perl object, manufacture a new Clownfish
65 * object suitable for supplying to a cfish_Foo_init() function.
66 */
67 CFISH_VISIBLE cfish_Obj*
68 cfish_XSBind_new_blank_obj(pTHX_ SV *either_sv);
69  
70 /** Create a new object to go with the supplied host object.
71 */
72 CFISH_VISIBLE cfish_Obj*
73 cfish_XSBind_foster_obj(pTHX_ SV *sv, cfish_Class *klass);
74  
75 /** Test whether an SV is defined. Handles "get" magic, unlike SvOK on its
76 * own.
77 */
78 CFISH_VISIBLE bool
79 cfish_XSBind_sv_defined(pTHX_ SV *sv);
80  
81 /** Test whether an SV is true. Wraps the expensive SvTRUE macro in a
82 * function.
83 */
84 CFISH_VISIBLE bool
85 cfish_XSBind_sv_true(pTHX_ SV *sv);
86  
87 /** Derive an SV from a Clownfish object. If the Clownfish object is NULL,
88 * the SV will be undef. Doesn't invoke To_Host and always returns a
89 * reference to a Clownfish::Obj.
90 *
91 * The new SV has single refcount for which the caller must take
92 * responsibility.
93 */
94 CFISH_VISIBLE SV*
95 cfish_XSBind_cfish_obj_to_sv_inc(pTHX_ cfish_Obj *obj);
96  
97 /** XSBind_cfish_obj_to_sv_inc, with a cast.
98 */
99 #define CFISH_OBJ_TO_SV_INC(_obj) \
100 cfish_XSBind_cfish_obj_to_sv_inc(aTHX_ (cfish_Obj*)_obj)
101  
102 /** As XSBind_cfish_obj_to_sv_inc above, except decrements the object's
103 * refcount after creating the SV. This is useful when the Clownfish
104 * expression creates a new refcount, e.g. a call to a constructor.
105 */
106 CFISH_VISIBLE SV*
107 cfish_XSBind_cfish_obj_to_sv_noinc(pTHX_ cfish_Obj *obj);
108  
109 /** XSBind_cfish_obj_to_sv_noinc, with a cast.
110 */
111 #define CFISH_OBJ_TO_SV_NOINC(_obj) \
112 cfish_XSBind_cfish_obj_to_sv_noinc(aTHX_ (cfish_Obj*)_obj)
113  
114 /** Null-safe invocation of Obj_To_Host.
115 */
116 static CFISH_INLINE SV*
117 10 cfish_XSBind_cfish_to_perl(pTHX_ cfish_Obj *obj) {
118 10 ▶ return obj ? (SV*)CFISH_Obj_To_Host(obj, NULL) : newSV(0);
Branch: 1 branch
BranchTrueFalseTotal
return obj ? (SV*)CFISH_Obj_To_Host(obj, NULL) : newSV(0); 6 4 10
119 }
120  
121 /** Convert a Perl SV to a Clownfish object of class `klass`.
122 *
123 * - If the SV contains a Clownfish object which passes an "isa" test against
124 * `klass`, return a pointer to it.
125 * - If the SV contains an arrayref and `klass` is VECTOR or OBJ, perform a
126 * deep conversion of the Perl array to a Vector.
127 * - If the SV contains a hashref and `klass` is HASH or OBJ, perform a
128 * deep conversion of the Perl hash to a Hash.
129 * - If `klass` is STRING or OBJ, stringify and return a String.
130 * - If all else fails, throw an exception.
131 *
132 * Returns an non-NULL, "incremented" object that must be decref'd at some
133 * point.
134 */
135 CFISH_VISIBLE cfish_Obj*
136 cfish_XSBind_perl_to_cfish(pTHX_ SV *sv, cfish_Class *klass);
137  
138 /** As XSBind_perl_to_cfish above, but returns NULL if the SV is undefined
139 * or a reference to an undef.
140 */
141 CFISH_VISIBLE cfish_Obj*
142 cfish_XSBind_perl_to_cfish_nullable(pTHX_ SV *sv, cfish_Class *klass);
143  
144 /** As XSBind_perl_to_cfish above, but returns an object that can be used for
145 * a while with no need to decref.
146 *
147 * If `klass` is STRING or OBJ, `allocation` must point to stack-allocated
148 * memory that can hold a String. Otherwise, `allocation` should be NULL.
149 */
150 CFISH_VISIBLE cfish_Obj*
151 cfish_XSBind_perl_to_cfish_noinc(pTHX_ SV *sv, cfish_Class *klass,
152 void *allocation);
153  
154 /** Return the contents of the hash entry's key as UTF-8.
155 */
156 CFISH_VISIBLE const char*
157 cfish_XSBind_hash_key_to_utf8(pTHX_ HE *entry, STRLEN *size_ptr);
158  
159 /** Perl-specific wrapper for Err#trap. The "routine" must be either a
160 * subroutine reference or the name of a subroutine.
161 */
162 cfish_Err*
163 cfish_XSBind_trap(SV *routine, SV *context);
164  
165 /** Locate hash-style params passed to an XS subroutine. If a required
166 * parameter is not present, locate_args() will throw an error.
167 *
168 * All possible valid param names must be passed in `specs`; if a
169 * user-supplied param cannot be matched up, locate_args() will throw an
170 * error.
171 *
172 * @param stack The Perl stack.
173 * @param start Where on the Perl stack to start looking for params. For
174 * methods, this would typically be 1; for functions, most likely 0.
175 * @param items The number of arguments passed to the Perl function
176 * (generally, the XS variable `items`).
177 * @params specs An array of XSBind_ParamSpec structs describing the
178 * parameters.
179 * @param locations On success, this output argument will be set to the
180 * location on the stack of each param. Optional arguments that could not
181 * be found have their location set to `items`.
182 * @param The number of parameters in `specs` and elements in `locations`.
183 */
184 CFISH_VISIBLE void
185 cfish_XSBind_locate_args(pTHX_ SV** stack, int32_t start, int32_t items,
186 const cfish_XSBind_ParamSpec *specs,
187 int32_t *locations, int32_t num_params);
188  
189 /** Convert an argument from the Perl stack to a Clownfish object. Throws
190 * an error if the SV can't be converted.
191 *
192 * @param value The SV from the Perl stack.
193 * @param label The name of the param.
194 * @param klass The class to convert to.
195 * @param allocation Stack allocation for Obj and String.
196 */
197 CFISH_VISIBLE cfish_Obj*
198 cfish_XSBind_arg_to_cfish(pTHX_ SV *value, const char *label,
199 cfish_Class *klass, void *allocation);
200  
201 /** Like XSBind_arg_to_cfish, but allows undef which is converted to NULL.
202 */
203 CFISH_VISIBLE cfish_Obj*
204 cfish_XSBind_arg_to_cfish_nullable(pTHX_ SV *value, const char *label,
205 cfish_Class *klass, void *allocation);
206  
207 /** Throw an error because of invalid number of arguments.
208 */
209 CFISH_VISIBLE void
210 cfish_XSBind_invalid_args_error(pTHX_ CV *cv, const char *param_list);
211  
212 /** Throw an error because of an undefined argument.
213 */
214 CFISH_VISIBLE void
215 cfish_XSBind_undef_arg_error(pTHX_ const char *label);
216  
217 /** Initialize ISA relations and XSUBs.
218 */
219 CFISH_VISIBLE void
220 cfish_XSBind_bootstrap(pTHX_ size_t num_classes,
221 const cfish_XSBind_ClassSpec *class_specs,
222 const cfish_XSBind_XSubSpec *xsub_specs,
223 const char *file);
224  
225 /** Destroy a Clownfish SV.
226 */
227 CFISH_VISIBLE void
228 cfish_XSBind_destroy(pTHX_ SV *sv);
229  
230 #define XSBIND_PARAM(key, required) \
231 { key, (int16_t)sizeof("" key) - 1, (char)required }
232  
233 /* Define short names for most of the symbols in this file. Note that these
234 * short names are ALWAYS in effect, since they are only used for Perl and we
235 * can be confident they don't conflict with anything. (It's prudent to use
236 * full symbols nevertheless in case someone else defines e.g. a function
237 * named "XSBind_sv_defined".)
238 */
239 #define XSBind_ClassSpec cfish_XSBind_ClassSpec
240 #define XSBind_XSubSpec cfish_XSBind_XSubSpec
241 #define XSBind_ParamSpec cfish_XSBind_ParamSpec
242 #define XSBind_new_blank_obj cfish_XSBind_new_blank_obj
243 #define XSBind_foster_obj cfish_XSBind_foster_obj
244 #define XSBind_sv_defined cfish_XSBind_sv_defined
245 #define XSBind_sv_true cfish_XSBind_sv_true
246 #define XSBind_cfish_obj_to_sv_inc cfish_XSBind_cfish_obj_to_sv_inc
247 #define XSBind_cfish_obj_to_sv_noinc cfish_XSBind_cfish_obj_to_sv_noinc
248 #define XSBind_cfish_to_perl cfish_XSBind_cfish_to_perl
249 #define XSBind_perl_to_cfish cfish_XSBind_perl_to_cfish
250 #define XSBind_perl_to_cfish_nullable cfish_XSBind_perl_to_cfish_nullable
251 #define XSBind_perl_to_cfish_noinc cfish_XSBind_perl_to_cfish_noinc
252 #define XSBind_hash_key_to_utf8 cfish_XSBind_hash_key_to_utf8
253 #define XSBind_trap cfish_XSBind_trap
254 #define XSBind_locate_args cfish_XSBind_locate_args
255 #define XSBind_arg_to_cfish cfish_XSBind_arg_to_cfish
256 #define XSBind_arg_to_cfish_nullable cfish_XSBind_arg_to_cfish_nullable
257 #define XSBind_invalid_args_error cfish_XSBind_invalid_args_error
258 #define XSBind_undef_arg_error cfish_XSBind_undef_arg_error
259 #define XSBind_bootstrap cfish_XSBind_bootstrap
260 #define XSBind_destroy cfish_XSBind_destroy
261  
262 /* Strip the prefix from some common ClownFish symbols where we know there's
263 * no conflict with Perl. It's a little inconsistent to do this rather than
264 * leave all symbols at full size, but the succinctness is worth it.
265 */
266 #define THROW CFISH_THROW
267 #define WARN CFISH_WARN
268  
269 #ifdef __cplusplus
270 }
271 #endif
272  
273 #endif // H_CFISH_XSBIND
274  
275  
« blib/lib/Clownfish/Vector.pm ↑ Summary