Monday, December 2, 2024

Passing parameters between local request handlers

In Gliimly, there are no "functions" or "methods" as you may be used to in other languages. Any encapsulation is a request handler - you can think of it as a simple function that executes to handle a request - it can be called from an outside caller (such as web browser, web API, or from a command-line), or from another handler.

By the same token, there are no formal parameters in a way that you may be used to. Instead, there are named parameters, basically name/value pairs, which you can set or get anywhere during the request execution. In addition, your request handler can handle the request body, environment variables, the specific request method etc. (see request). Here though, we'll focus on parameters only.

You'll use set-param to set a parameter, which can then be obtained anywhere in the current request, including in the current handler's caller or callee. Use get-param to obtain a parameter that's set with set-param.

Parameters are very fast - they are static creatures implemented at compile time, meaning only fixed memory locations are used to store them (making for great CPU caching), and any name-based resolution is used only when necessary, and always with fast hash tables and static caching.
Calling one handler from another
In this article, we'll talk about call-handler which is used to call a handler from within another handler.

Here you'll see a few examples of passing input and output parameters between requests handlers. These handlers are both running in the same process of an application (note that application can run as many processes working in parallel). To begin, create an application:
mkdir param
cd param
gg -k param

You'll also create two source files ("local.gliim" and "some.gliim") a bit later with the code below.
Simple service
Let's start with a simple service that provides current time based on a timezone as an input parameter (in file "local.gliim"):
 begin-handler /local/time
     get-param tzone // get time zone as input parameter (i.e. "EST", "MST", "PST" etc.)
     get-time to curr_time timezone tzone
     @<div>Current time is <<p-out curr_time>></div>
 end-handler

In this case, HTML code is output. Make the application:
gg -q --public

and run it from command line (just as if it were called from a web browser):
gg -r --req="/local/time" --silent-header --exec

with the result something like:
<div>Current time is Mon, 02 Dec 2024 16:27:03 EST</div>

Calling request from another, example #1
In this example, one request handler calls another from within the same process of an application using call-handler.

For instance, here's the caller code which calls the above "/local/time" service (in file "some.gliim"):
 begin-handler /some/service
     set-param tzone="EST" // set the input parameter to be obtained by /local/time handler
     call-handler "/local/time"
 end-handler

and in this case the output of the "/local/time" would simply become output of "/some/service" (and be presumably sent to a client like web browser).

You can also, however, return the string to the caller using set-param - here's the reworked "/local/time" service (in file "local.gliim"):
 begin-handler /local/time
     get-param tzone
     get-time to curr_time timezone tzone
     set-param curr_time // set the return parameter to be obtained by the caller
 end-handler

The result parameter will be obtained in the caller, and then output as HTML from there (we could save it to a file instead, or whatever), so here's what it'd be now in file "some.gliim":
 begin-handler /some/service
     set-param tzone="EST" // set input parameter used by "/local/time"
     call-handler "/local/time"
     get-param curr_time // get parameter that was set by "/local/time"
     @<div>Current time is <<p-out curr_time>></div>
 end-handler

Make the project and run it:
gg -q --public
gg -r --req="/some/service" --silent-header --exec

with the similar end result.
Calling request from another, example #2
Consider this handler, which checks if number is even, and returns true or false (file "check.gliim"):
 begin-handler /check/even
     get-param num type number // get input parameter
     if-true num every 2
         set-param is_even = true // set output parameter
     else-if
         set-param is_even = false // set output parameter
     end-if
 end-handler

Here's calling it from another handler: 
 begin-handler /some/task
     set-param num = 23 // set input parameter for /check/even
     call-handler "/check/even"
     get-param is_even type bool //get output from /check/even
     if-true is_even equal true
         @EVEN
     else-if
         @ODD
     end-if
 end-handler

Make the project and run it:
gg -q --public
gg -r --req="/some/task" --silent-header --exec

with the result (since 23 is an odd number):
ODD

Conclusion
Gliimly is a language and a platform built to provide native web services, and everything in it is centered around the notion of handling service calls. Simple high-performance name/value constructs rule the communication between handlers on the network as well as locally. Suffice it to say, Gliimly's not a classic C-like programming language (though ironically is built in C and compiles to C).