The SoLoad Foreign Function Server (Part III) – Intermediate Usage
This is the third post in a series or four. It comes after Introduction and Basic Usage.
In the last two posts, I discussed the reason for SoLoad, and how to use it. The basic usage guide skipped a few of the more complex features in the interest of simplicity. The guide only showed how to use numeric types, and not pointers, strings, or user-defined types. Also, it didn't mention the use of loadable definition files. This post will discuss those features.
Strings
Strings in SoLoad are fairly simple to use. Any sequence of characters, separated by spaces, will be read as a string if its type says so. To add spaces to a string, simply use quotes. To add quotes to a string, use a backslash to escape them, and to add a backslash, use two backslashes. Strings in SoLoad look pretty much like standard C strings.
Say that we have a hypothetical "message" function, which we want to load from a library and use. It takes a string (char*) as an argument, and puts it in a message box. It has no return value.
Loading this function is simple. It looks like
(
is also acceptable)
Calling it is just that simple, too. For a single word output, you can just say
and get "Hello" as a message. Quotes are needed if we want to use spaces in the string:
And quotation marks can be escaped with a backslash:
Pointers
Using pointers in SoLoad is very simple. If all you need to do is to call functions that return pointers, and pass those values to other functions, you can just do that.
0x2364DADB
> call get_value 0x2364DADB
37
If you want to be able to create new pointers or get their values, however, there are a few new commands to master.
type
The
command registers a new type with SoLoad. It has pretty much the same syntax as the argument part of loading a function.
new
The
command creates an instance of a type in memory, and returns a pointer to it.
value
The
command returns the values contained in a struct at the specified address.
37 "Hello, World!"
delete
The
command frees the struct at the given address.
deltype
The del
command deletes a type that was already registered with SoLoad. WARNING: Doing this will probably make SoLoad unable to delete remaining instances of this type.
Def Files
All of the commands for opening a library and loading functions work well enough for one-shot uses, but they can get a little tedious when loading an entire library. Also, I think that bindings developed for SoLoad should easily be usable by any program that uses SoLoad. I intend to provide this functionality through loadable definitions files. These files are simply text files that list various bits of information necessary to load a library and its functions. They are incapable of deleting data, they can only open libraries, load functions, and define types. They look like this:
name sdl paths /usr/lib/libSDL.so /usr/lib/SDL.so /usr/local/lib/libSDL.so function SDL_Init int 1 uint32 function SDL_Quit void 0 function SDL_SetVideoMode pointer 4 int int int uint32 function SDL_WM_ToggleFullScreen int 1 pointer type struct_one 2 int int type struct_two 2 int string
The "name" statement declares a short name for the library.
The "paths" statement lists paths that the library might be found at. They will be tried one at a time in order until one is opened successfully.
The "function" statement loads a function from the library. "function ..." is equivalent to "load <short-name> ..."
The "type" statement does the exact same thing as the "type" statement does in interactive mode.
And that concludes the intermediate level usage tutorial for SoLoad. It should now be possible for you to load and use any kind of function that SoLoad supports. You should also be able to interact with structures, pointers, and strings. In the next (and probably final) post in this series, I will detail the process of creating an FFI library for a dialect of Scheme (just as soon as I get around to writing the library myself).
The SoLoad Foreign Function Server (Part II) – Basic Usage
I'm sorry this post has taken so long. I started writing it over a week ago, but by the time it was finished, it looked more like a reference document than a guide to basic usage. I decided that a document like that would be much better if placed on the SoLoad Wiki.
After much editing down, I ended up with this tutorial, which is much easier to read.
The SoLoad Foreign Function Server is a program that allows interpreters and scripting languages to call C functions. The only requirements for use are those necessary to start a process and communicate with it.
Previously, I explained the need for and the purpose of SoLoad. In this post, I will explain how it is used in a command-line session.
Starting
SoLoad has, at the time of this writing, two methods of communication with the outside world. It can talk over the standard input/output streams, and via TCP. To start SoLoad and control it over stdin, use the command
Similarly, to use it over TCP, just say
Once you have connected to the port via telnet, there should be no further differences between the different communications methods.
Opening a Library
To open a library, use the
command. The
command takes one or two arguments. The first is the path to the library, and the second is an optional short name for the library. If provided, this short name can be used interchangeably with the library identifier that is returned by the command.
For the purposes of this example, we will try to open the
shared library. I assume that the path to it is "/lib/libm.so.6" . If it is different on your system, the command will need to be modified accordingly.
So, to open the libm library, the command goes
This opens the library and assigns it a short name of "libm".
Loading a Function
Loading a function from a library is done with the
command. The load command takes as its arguments: a library identifier, the name of the function to be loaded, the return type, the number of arguments to the function, and the types of all the arguments. For our purposes, the command will look like
If, however, we had opted not to provide a short name for the library when opening it, the call would probably look something more like
Calling a Function
To call a function, use the
command takes a function identifier, and a number of arguments. For us, it will look like
and will return the result of the call.
Exiting
To exit, simply type
. Everything should automatically be unloaded, and SoLoad will close.
Cleanup (Optional)
close <em>library-id</em>
The following functions don't usually need to be used. They are provided simply because doing so adds barely any complexity to the program, and allows use in situations where libraries must be continually loaded and unloaded without exiting, and without filling up all available memory with old library references.
Again, SoLoad will automatically do this cleanup when it exits, so you are free to just quit now if you wish.
To unload a function, use the
command. It takes a function identifier as its only argument. It would look like
Similarly, to close a library, simply say
The library is closed, and functions loaded from it are no longer valid. (Note: Closing a library does not automatically unload all of its functions, but those functions will still be unloaded at exit)
A More Complex Example
The following is a transcript of a simple interaction with the SDL library. SoLoad will be used to open SDL, create a window, and then quit.
> soload stdin > open /usr/lib/libSDL.so sdl 0x9fd7058 > load sdl SDL_Init int 1 uint32 0x9fd7be8 > load sdl SDL_SetVideoMode pointer 4 int int int uint32 0x9fd7bc8 > load sdl SDL_Quit void 0 0x9fd7d88 > call SDL_Init 0 0 > call SDL_SetVideoMode 640 480 16 0 0xa004998 > call SDL_Quit @� > exit exit
Stay tuned for the next post in the series, in which I will discuss intermediate level usage (structs and strings).
A Scheme Syntax-Rules Primer
Scheme has a wonderfully powerful hygienic macro system. Unfortunately, explanations on how to use it are few and far between. R5RS is utterly incomprehensible to anyone who doesn't already have a firm grounding in hygienic macro systems, and TYSiFD's section on macros dates from a time before syntax-rules and hygiene.
So this here is my attempt to share what I've learned over the past few days with regards to syntax-rules macros. Bear in mind that at the time of writing this, I have known how to use syntax-rules since yesterday, but my knowledge seems to be complete enough to write a working module system, so here's my attempt to pass on what I've learned.
First things first. You use define-syntax to create a top level binding, and let-syntax bears the same relationship to define-syntax as you'd expect.
;; a top-level binding of a macro
(define-syntax macro
<syntax transformer>)
That much is pretty clear from reading R5RS, now we need to figure out how to write the syntax transformer. There are a few ways to do this, but the best way for beginners is to use syntax-rules, which avoids inadvertent variable capture and other such nasties automatically, and uses a rather elegant pattern matching language.
We'll start by trying to write a simple macro, while. This will just be a standard looping construct that keeps executing over and over until its condition becomes false. We want its usage to look something like this:
(define x 0)
(while (< x 5)
(set! x (+ x 1))
(print x))
So first, we need the define-syntax form.
<syntax transformer>)
Next, we need to write the syntax transformer itself. This is where syntax-rules comes into play. Syntax-rules uses pattern matching and text substitution to allow you to make some pretty advanced macros. It looks like:
(syntax-rules (<keywords>)
((<pattern>) <template>)
...
((<pattern>) <template>)))
I will explain keywords later. For now, just leave that bit blank. What we're interested in are those ((<pattern>) <template>) pairs. Each <pattern> is just that, a pattern of code that will be matched. In our case, we want to match the pattern:
Where the '...' signifies that body may contain one or more forms. Luckily for us, this is exactly the syntax that syntax-rules wants to see, so we can just plug it in, giving us:
(syntax-rules ()
((while condition body ...) <template>)))
So far so good. Now we just have to fill in the other half, with a suitable <template>
Before we can write the <template>, though, we have to decide what we want the code to end up looking like. Since this isn't a guide to scheme code in general, I'll just go ahead and say that we want the output to look like:
(let loop ()
(if condition
(begin
body ...
(loop))
#f))
Got that? Okay, now we've just got to put this in our syntax-rules macro as a template. By another startling coincidence, this is exactly what the template code is expected to look like. We just plug in that code, and our final result is:
(syntax-rules ()
((while condition body ...)
(let loop ()
(if condition
(begin
body ...
(loop))
#f)))))
Just plug that into your scheme interpreter, and our while loop from earlier should execute perfectly.
Now let's try to write something a little more complicated. We want to write a for loop similar to the one that Python has. This should be a pretty easy task, since it's basically just syntactic sugar for scheme's map function.
Our goal is to be able to write a piece of code taking the form:
<body ...>)
And have it expand to:
(for-each (lambda (<element>)
<body ...>) <list>)
Our first try would probably look something like this:
(syntax-rules ()
((for element in list body ...)
(map (lambda (element)
body ...)
list))))
This works, but there's one issue with it. All of the following are valid and work exactly the same:
(for i fnord '(0 1 2 3 4) (print i))
(for i some-other-keyword '(0 1 2 3 4) (print i))
This is not so much of a problem in the case of a for loop, but what if you wanted to add another rule later, so that
(print i))
will also work? The solution to this problem is in that <keywords> argument that we glossed over earlier. Change the keywords list to include 'in' (and, for good measure, 'as'), and it will allow those symbols, and only those symbols, in places where they are mentioned. This change leaves us with:
(syntax-rules (in as)
((for element in list body ...)
(map (lambda (element)
body ...)
list))
((for list as element body ...)
(map (lambda (element)
body ...)
list))
Or, for simplicity (thanks to Dan Prager for pointing this out)
(syntax-rules (in as)
((for element in list body ...)
(map (lambda (element)
body ...)
list))
((for list as element body ...)
(for element in list body ...))))
And if we load this code into our scheme interpreter of choice, we should have two fully functional little bits of new syntax.
Hopefully this guide will help shed some light on the arcane subject that is the Scheme macro system, and hopefully I will never have to learn enough about syntax-case to write a tutorial on it.