Server API

Gliimly can be used in extended-mode, where non-Gliimly code or libraries can be linked with your application.

Such code can be from a library (see --llflag and --cflag options in gg), or can be written directly as C code, i.e. files with .c and .h extension together with your Gliimly application. To do this, use call-extended statement.

Any function with C linkage can be used provided:

its parameters are (by value or reference) only of type: "int64_t" (number type in Gliimly), "bool" (bool type in Gliimly) or "char *" (string type in Gliimly).
it must not return any value (i.e. it must have a "void" return type).

When allocating strings in extended code, you must use Gliimly memory management functions. These functions are based on standard C library (such as malloc or free), but are not compatible with them because Gliimly manages such memory on top of the standard C library.

The functions you can use are:

char *gg_strdup (char *s) which creates a copy of a null-terminated string "s". A pointer to memory data is returned.
char *gg_strdupl (char *s, gg_num from, gg_num l) which creates a copy of memory data pointed to by "s", starting from byte "from" of length "l". Note that "from" is indexed from 0. A pointer to memory data is returned.
void *gg_malloc(size_t size) which allocates memory of size "s" and returns a pointer to it.
void *gg_calloc(size_t nmemb, size_t size) allocates "nmemb" blocks of memory (each of size "size") and returns a pointer to it. Memory is initialized to all zero bytes.
num gg_mem_get_id (void *ptr) returns Gliimly memory handle for memory "ptr".
void *gg_realloc(gg_num r, size_t size) reallocates memory identified with Gliimly memory handle "r" (see gg_mem_get_id()) to a new size of "size" and returns a pointer to it. Note that you can only reallocate the memory you created with gg_malloc() and gg_calloc() - do not attempt to reallocate Gliimly memory passed to your function. Gliimly in general never reallocates any existing memory in any statement.
void gg_mem_set_len (gg_num r, gg_num len) sets the length of memory identified with Gliimly memory handle "r" to "len" bytes. Note that all Gliimly memory must have a null-byte at the end for consistency, regardless of whether such memory holds pure binary data or an actual null-delimited string. So for example, a string "abc" would have "len" set to 4 to include a null byte, and binary data "\xFF\x00\x01" (which consists of 3 bytes, the middle of which is a null byte) would have "len" also set to 4 and you would place an extra zero byte at the end of it even if it's not part of the actual useful data. Note that whatever memory length you set, it must be lesser or equal to the length of memory you have actually allocated.
num gg_mem_get_len (gg_num r) returns the length of memory identified with Gliimly memory handle "r". The length returned is 1 bytes less than the memory set by gg_mem_set_len(), so for example for string "abc" the return value would be 3, as it would be for "\xFF\x00\x01".

You can use gg_malloc(), gg_calloc() and gg_realloc() to create new Gliimly-compatible memory - and assuming you have set the last byte of any such memory to a null byte, the resulting memory will be properly sized for Gliimly usage.

If you have memory that's already provided from elsewhere, you can use gg_strdup() or gg_strdupl() to create a copy of it that's compatible with Gliimly.

If Gliimly memory you created with these functions has extra unused bytes, you can use either gg_realloc() to reduce its footprint, or you can use gg_mem_set_len() to set its length.

Note that if you use C code included with a Gliimly project, you must include "gliim.h" file in each of them. You do not need to manually include any other ".h" files (header files), as they will be automatically picked up.

Examples

Place the following files in a separate directory for demonstration purposes.

In this example, "example.gliim" will use C functions from "example.c", and "example.h" will have declarations of those functions. File "example.c" implements a factorial function, as well as a function that will store the factorial result in an output message that's allocated and passed back to your Gliimly code:

 #include "gliim.h"

 void get_factorial(gg_num f, gg_num *res)
 {
     *res = 1;
     gg_num i;
     for (i = 2; i <= f; i++) {
         *res *= i;
     }
 }

 #define MEMSIZE 200
 void fact_msg (gg_num i, char **res)
 {
     // gliim rule: outgoing string must NOT free or realloc its incoming value
     // all else is allowed
     char *r = gg_malloc (MEMSIZE);
     gg_num f;
     get_factorial (i, &f);
     gg_num bw = snprintf(r, MEMSIZE, "Factorial value (message from C function) is %ld", f) + 1;
     // reduce memory footprint to match the memory used (including the null byte)
     // you can also use gg_mem_set_len() with bw as length for higher performance 
     // (but also higher memory usage)
     *res = gg_realloc (gg_mem_get_id(r), bw);
 }

File "example.h" declares the above functions:

 void get_factorial(gg_num f, gg_num *res);
 void fact_msg (gg_num i, char **res);

File "example.gliim" will call the above functions and display the results:

 extended-mode

 begin-handler /example

     set-number fact
     call-extended get_factorial (10, &fact)
     @Factorial is <<p-num fact>>

     set-string res
     call-extended fact_msg (10, &res)
     p-out res
     @
 end-handler

Create application "example":

sudo mgrg -i -u $(whoami) example

Make the application:

gg -q

Run it:

gg -r --req="/example" --exec --silent

The output is, as expected:

Factorial is 3628800
Factorial value (message from C function) is 362880