| 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
| Branch | True | False | Total |
| 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 |
|
| |