This post picks up on the first part of this interop mini-series (Calling C and C++ from Common Lisp). I recommend checking out that post first in order to make sense of this one.
Contents
Intent
The scope of this post is to cover interop with C and C++ code from Common Lisp using callbacks. In case you are not sure about what callbacks are, please check the first part of this post out – Callbacks special.
We will continue to use the cffi library for our demo here as well.
Demo
For this demo, let’s pick a very simple example.
We have a person type which has the following slots/fields – name, gender, and age. From our Common Lisp code, we want to instantiate an instance of person, and then use a function in a native library, prefix_name to append either “Mr.” or “Miss” in front of the person’s name, depending on the value of the gender slot (0 for female, anything else for male).
First we define the interface for the native library (in callback_demo.h:
#ifndef __CALLBACK_DEMO_H__
#define __CALLBACK_DEMO_H__ "callback_demo.h"
typedef struct person {
char* name;
int gender;
int age;
} person;
#ifdef __cplusplus
extern "C" {
#endif
void prefix_name(person*, void (*)(person*));
#ifdef __cplusplus
}
#endif
#endif
We then write the code containing the prefix_name function that will invoke our callback function (in callback_demo.c:
#include
#include
#include
#include "callback_demo.h"
#define MAXSIZE 50
char* concatenate_names(const char* prefix, char* name)
{
int len = strlen(prefix) + strlen(name) + 1;
char* full_name = (char*)malloc(len * sizeof(char));
if (full_name != NULL) {
char* cp = full_name;
while (*prefix != '\0')
*cp++ = *prefix++;
*cp++ = 0x20;
while (*name != '\0')
*cp++ = *name++;
*cp = '\0';
return full_name;
}
return name;
}
void prefix_name(person* p, void (*cb)(person*))
{
const char* MISTER = "Mr.";
const char* MISS = "Ms.";
char* res = NULL;
// 0 - female, anything else male
res = p->gender == 0 ? concatenate_names(MISS, p->name) :
concatenate_names(MISTER, p->name);
strcpy(p->name, res);
(*cb)(p);
}
void sample_callback(person* p)
{
printf("%s, %s, %d\n", p->name, p->gender == 0 ? "Female" : "Male", p->age);
}
int main()
{
person rich;
rich.name = (char*)malloc(MAXSIZE * sizeof(char));
strcpy(rich.name, "Rich");
rich.gender = 1;
rich.age = 49;
prefix_name(&rich, &sample_callback);
return 0;
}
Explanation: The code is relatively straightforward. As can be seen from the header file, prefix_name is the entry point to the library (and the one which gets invoked from the Common Lisp code).
The prefix_name function takes an instance of the person structure as well as a callback function. Note the signature of the callback function:
void (*)(person*).
This callback function expects to be passed a modified instance of the person instance that is the first parameter of the prefix_name function.
The logic is very simple – simply check for the gender field, and then depending on whether it is 0 or some other way, update the name field of the person instance by prepending “Miss” or “Mr.” respectively.
Finally, the callback function cb is invoked, passing control back to the client code.
All right, now we compile the code into a library, libcallbackdemo.dylib:
Timmys-MacBook-Pro:Demo z0ltan$ clang -dynamiclib -o libcallbackdemo.dylib callback_demo.c Timmys-MacBook-Pro:Demo z0ltan$ ls callback_demo.c callback_demo.h libcallbackdemo.dylib
Excellent!
Now we focus on the Common Lisp bit. This part is relatively straight forward. Let’s see the code in action first, and then a bit of explanation.
First the code that calls the native library function, prefix_name (in c-to-lisp.lisp):
;;;; Demonstrating how Common Lisp can invoke functions in C or C++ code, which then themselves invoke a callback function written in Common Lisp.
;;;; This helps in those cases when Common Lisp needs to make use of some
;;;; functionality present in a native library which is written using callbacks.
(require 'cffi)
(defpackage :c-to-lisp-user
(:use :cl :cffi))
(in-package :c-to-lisp-user)
;;; Callback demo - first define the foreign library
;;; containing the function which takes a callback function.
(define-foreign-library libcallbackdemo
(:darwin "libcallbackdemo.dylib")
(:unix "libcallbackdemo.so")
(t (:default "libcallbackdemo.dylib")))
(use-foreign-library libcallbackdemo)
;;; define Common Lisp equivalent of the C structure
(defcstruct person
(name :string)
(gender :int)
(age :int))
;;; define the implementation of the callback
(defcallback print-prefixed-person :void
((ptr (:pointer (:struct person))))
(with-foreign-slots ((name gender age) ptr (:struct person))
(format t "Name: ~a, Gender: ~a, Age: ~d~%"
name
(if (zerop gender) "Female" "male")
age)))
;;; invoke the callback in the C library with a new instance of
;;; a person object
(defun test-callback ()
(with-foreign-object (rich '(:struct person))
(setf (foreign-slot-value rich '(:struct person) 'name) "Rich"
(foreign-slot-value rich '(:struct person) 'gender) 1
(foreign-slot-value rich '(:struct person) 'age) 49)
(foreign-funcall "prefix_name"
:pointer rich
:pointer (callback print-prefixed-person)
:void))
(with-foreign-object (vigdis '(:struct person))
(setf (foreign-slot-value vigdis '(:struct person) 'name) "Vigdis"
(foreign-slot-value vigdis '(:struct person) 'gender) 0
(foreign-slot-value vigdis '(:struct person) 'age) 28)
(foreign-funcall "prefix_name"
:pointer vigdis
:pointer (callback print-prefixed-person)
:void)))
;;; unload the foreign library
(close-foreign-library 'libcallbackdemo)
And the output:
C-TO-LISP-USER> (test-callback) Name: Mr. Rich, Gender: male, Age: 49 Name: Ms. Vigdis, Gender: Female, Age: 28 ; No value
Explanation: This code is also quite simple. We begin by defining the native library, and then loading it.
Next, we define the callback function using the cffi:defcallback macro. The defined callback function, print-prefixed-person uses a pointer to a person instance (which is returned by the prefix_name function inside libcallbackdemo.dylib), and so need to define the person structure first.
For that, we use another macro, cffi:defcstruct. As you can see, there is simply an exact representation of the structure defined in callback_demo.h albeit in a Lispy manner.
cffi:with-foreign-slots is a very important macro that destructures its pointer argument into the supplied slots. Note that the slot names must be the same as that provided in the person structure defined in the Common Lisp code. Note the use of cffi:foreign-slot-value instead of cffi:mem-aref as in the previous post. The rule of thumb is this – use cffi:foreign-slot-value when accessing slots, and use cffi:mem-aref when accessing atomic types.
Finally, we actually invoke the prefix_name function from test_callback. We create two instances of the person structure, and then we pass the callback function in the foreign-funcall invocation using the macro cffi:callback.
cffi:callback simply returns a pointer which is what the prefix_name function in libcallbackdemo.dylib requires. The cycle is complete!
As we can see from the output, the names are prepended with the correct suffix.
Basic useful functions
Here is the summarised list of the additional functions that were used in the demo:
- cffi:defcstruct
- cffi:defcallback
- cffi:with-foreign-slots
- cffi:foreign-slot-value
- cffi:callback
Conclusion
The cffi library is a very powerful and well-designed library for dealing with native libraries. It is also quite vast, and I would most definitely recommend browsing through the official manual for further examples, and also for usage patterns for your specific needs.
Next up, I will demonstrate interop between C (and C++) and Java using the JNA library, which is far superior to the alternative of using pure JNI. That will be also be in two parts.
Talking with a Lisp 