The language of Orchids includes several primitives, but you may want to add new ones.<\/p>\n
The main primitives of Orchids are coded in In writing a primitive, you should first decide of its type.\u00a0 This is a good safeguard again bugs, and will be needed at the end of this post.\u00a0 The We then start to write the primitive.\u00a0 Let us name it The\u00a0 The variable Here In case we had several arguments, you should pay attention to the fact that There is another macro ( <\/p>\n <\/p>\n Now we convert the string to an integer, using the Before we do so, though, we must check that We therefore write:<\/p>\n The call to the macro (By the way, this is not the actual code. I modified it so as to make it easier to explain how you could<\/em> write it.)<\/p>\n Note that even though this is an error case, we still have to pop the argument from the stack, using If we had been given three arguments, we should have called <\/p>\n <\/p>\n We also explicit check the type.\u00a0 This is not needed, since Orchids embeds a static type-checker that guarantees that the function will only ever be called with the right type.\u00a0 I will do as though we needed to check the type at run-time (this switch is anyway needed to handle the difference between real and virtual strings, I will discuss this below):<\/p>\n We now build an Orchids integer value, pop the stack, and push the resulting value:<\/p>\n Let me stress another point.\u00a0 Since the argument to The code of our primitive is ready.<\/p>\n <\/p>\n <\/p>\n The final step is to make sure that Orchids knows<\/em> about our primitive.\u00a0 We must link it into Orchids’ virtual machine.\u00a0 There are several ways to do that.<\/p>\n where For the purposes of static type-checking,\u00a0 The structs This is a The id<\/em> field is unused. It was probably meant to be some sort of unique identification number, but does not serve any purpose actually.<\/li>\n<\/ul>\n That’s it!\u00a0 Now you can use code such as <\/p>\n","protected":false},"excerpt":{"rendered":" The language of Orchids includes several primitives, but you may want to add new ones. The main primitives of Orchids are coded in lang.c. Some others are provided by modules.\u00a0 Let us look at a simple example, that of the function int_from_str, which converts a string such as “12” to the corresponding integer (12 here).<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4],"tags":[],"class_list":["post-163","post","type-post","status-publish","format-standard","hentry","category-virtual-machine"],"_links":{"self":[{"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdev\/index.php?rest_route=\/wp\/v2\/posts\/163","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdev\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdev\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdev\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdev\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=163"}],"version-history":[{"count":14,"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdev\/index.php?rest_route=\/wp\/v2\/posts\/163\/revisions"}],"predecessor-version":[{"id":298,"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdev\/index.php?rest_route=\/wp\/v2\/posts\/163\/revisions\/298"}],"wp:attachment":[{"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdev\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=163"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdev\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=163"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdev\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=163"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}lang.c<\/code>. Some others are provided by modules.\u00a0 Let us look at a simple example, that of the function int_from_str<\/code>, which converts a string such as \"12\"<\/code> to the corresponding integer (12 here).<\/p>\nint_from_str<\/code> function should take a string (either a string or a virtual string) and return an integer.<\/p>\nissdl_int_from_str<\/code>. We write:<\/p>\nstatic void issdl_int_from_str(orchids_t *ctx, state_instance_t *state,\r\n void *data)\r\n{\r\n\u00a0 ovm_var_t *str;\r\n\u00a0 ovm_var_t *i;\r\n\r\n<\/pre>\nctx<\/code>\u00a0parameter holds the general Orchids context, as for most other Orchids functions, and\u00a0state<\/code>\u00a0holds the current state of the machine. \u00a0We shall use the latter mostly to handle the machine’s stack: all primitives consume their arguments from the stack and push back the result onto the stack. \u00a0I will discuss the\u00a0data<\/code>\u00a0parameter much later in this post, and only briefly.<\/p>\ni<\/code> will eventually hold the result. As I said, our primitive will take its arguments from the Orchids stack. \u00a0We get the value of our unique\u00a0argument, from the stack, into str<\/code>\u00a0as follows:<\/p>\n\u00a0\u00a0 str = (ovm_var_t *)STACK_ELT(ctx->ovm_stack, 1);<\/pre>\n
ctx->ovm_stack<\/code> is the stack of the Orchids virtual machine.\u00a0 We get our arguments from the stack.\u00a0 We shall also need to pop the arguments from the stack and push the result back, see below.\u00a0 For now, we just read elements from the stack using the STACK_ELT<\/code> macro.<\/p>\nSTACK_ELT(ctx->ovm_stack, 1)<\/code> returns the last<\/em> argument.\u00a0 STACK_ELT(ctx->ovm_stack, 2)<\/code> returns the next-to-last argument, and so on. For example, to obtain the three arguments of a 3 argument function, you should write arg3 = (ovm_var_t *)STACK_ELT(ctx->ovm_stack, 1); arg2 = (ovm_var_t *)STACK_ELT(ctx->ovm_stack, 2); arg1 = (ovm_var_t *)STACK_ELT(ctx->ovm_stack, 3);<\/code>.<\/p>\nSTACK_POP<\/code>) that allows you to read the element at the top of the stack and pop it at the same time.\u00a0 Don’t use it unless you really know what you do.\u00a0 The nice thing about STACK_ELT<\/code> is that, since it keeps the element read on the stack, it won’t be freed by the garbage-collector<\/a>: anything on the stack is considered in use, and won’t be freed.<\/p>\n
\norchids_atoi<\/code> function. This works just like atoi<\/code>, except the string need not be 0-terminated. Recall that Orchids strings are given with an explicit length.<\/p>\nstr<\/code> is not NULL<\/code>. Indeed, any argument may be NULL<\/code>, as a result of a run-time error typically (division by zero, type error, etc.)<\/p>\n if (str==NULL)\r\n {\r\nerr:\r\n DebugLog(DF_OVM, DS_DEBUG, \"issdl_int_from_str(): param error\\n\");\r\n STACK_DROP(ctx->ovm_stack, 1);\r\n PUSH_VALUE(ctx, NULL);\r\n }\r\n<\/pre>\nDebugLog<\/code> is not necessary, but helps in case of bugs.<\/p>\nSTACK_DROP<\/code>, and push a value: here, NULL<\/code>, since we ran into an error.<\/p>\nSTACK_DROP(ctx->ovm_stack, 3)<\/code>, as you might expect.<\/p>\n
\n else switch (TYPE(str))\r\n {\r\n long value;\r\n\r\n case T_STR:\r\n value = orchids_atoi(STR(str), STRLEN(str));\r\n<\/pre>\n\u00a0\u00a0\u00a0\u00a0\u00a0 i = ovm_int_new(ctx->gc_ctx, value);\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 STACK_DROP(ctx->ovm_stack, 1);\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 PUSH_VALUE(ctx,i);\r\n break;<\/pre>\n
int_from_str<\/code> is meant to be a string, it can actually be either a real string<\/a> or a virtual string<\/a>, and both<\/em> cases must be handled, with results that should look identical to the outside observer.\u00a0 So we proceed and do\u00a0the same thing for virtual strings:<\/p>\n\u00a0\u00a0\u00a0\u00a0\u00a0 case T_VSTR:\r\n value = orchids_atoi(VSTR(str), VSTRLEN(str));\r\n i = ovm_int_new(ctx->gc_ctx, value);\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 STACK_DROP(ctx->ovm_stack, 1);\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 PUSH_VALUE(ctx,i);\r\n break;\r\n default:\r\n goto err; \/\/ No need to duplicate code\r\n }\r\n}<\/pre>\n
\n\n
register_lang_function<\/code> in your module’s preconfig code. Here, write:\nregister_lang_function(ctx, issdl_int_from_str, \"int_from_str\",\r\n 1, int_of_str_sigs,\r\n m_unknown_1,\r\n \"convert a string to the integer it represents in decimal.\"\r\n NULL);\r\n<\/pre>\n
ctx<\/code> is the Orchids context, issdl_int_from_str<\/code> is our function, m_unknown_1<\/code> is a function pointer that instructs Orchids about the monotonicity of the int_of_str_sigs<\/code> function, \"int_from_str\"<\/code> is the name by which we wish to call it in Orchids signatures, 1<\/code> is its expected number of arguments,\u00a0int_of_str_sigs<\/code> is required for static type-checking (see below), the final string is a documentation string, and the final parameter (here,\u00a0NULL<\/code>) will be passed as the\u00a0data<\/code>\u00a0argument to\u00a0issdl_int_from_str<\/code>. \u00a0(The latter is useful, for example, if you write a new primitive in a module, and you wish to use module-specific data in your primitive: pass the relevant\u00a0mod_entry_t *<\/code>\u00a0data to\u00a0register_lang_function()\u00a0<\/code>instead of\u00a0NULL<\/code>; in the primitive, cast back its\u00a0data<\/code>\u00a0argument to\u00a0mod_entry_t *mod<\/code>, and obtain your private, module-specific data as\u00a0mod->config<\/code>, say.)<\/p>\nint_of_str_sigs<\/code> is an array of possible type signatures for our function.\u00a0 Our function has only one intended signature, namely it should map strings to ints.\u00a0 Here is this signature, as a C declaration:<\/p>\nstatic type_t *int_of_str_sig[] = { &t_int, &t_str };<\/pre>\nt_int<\/code> and t_str<\/code> are predefined, and mean int<\/code> and string<\/code> (either real or virtual), respectively.\u00a0 Beware that the return type comes first<\/em>, followed by the list of argument types.\u00a0 There should be exactly n<\/em>+1 pointers in this array, where n<\/em> is the arity of the function.
\nFinally, we need to provide register_lang_function()<\/code> with an array<\/em> of possible type signatures, so the array we pass it as 5th argument is:<\/p>\nstatic type_t **int_of_str_sigs[] = { int_of_str_sig, NULL };<\/pre>\nNULL-<\/code>terminated array of signatures. This kind of complication is needed for functions that have several signatures, such as comparison functions for example, whose array of signatures is:<\/p>\nstatic type_t **cmp_sigs[] = {\r\n int_cmp_sig, uint_cmp_sig, ipv4_cmp_sig, ipv6_cmp_sig,\r\n str_cmp_sig, bstr_cmp_sig, ctime_cmp_sig, timeval_cmp_sig,\r\n float_cmp_sig, NULL\r\n};\r\n<\/pre>\n<\/li>\nissdl_function_g<\/code> table of known functions, in lang.c<\/code>, say:\n { issdl_int_from_str, id<\/em>, \"int_from_str\", 1, int_of_str_sigs, m_unknown_1,\r\n \"convert a string to the integer it represents in decimal.\", NULL },\r\n<\/pre>\n$x = int_from_str($y);<\/code> in your Orchids signatures.<\/p>\n