The FFI support in Pony uses the C application binary interface (ABI) to interface with native code. The C ABI is a calling convention, one of many, that allow objects from different programming languages to be used together.

Writing a C library for Pony

Writing your own C library for use by Pony is almost as easy as using existing libraries.

Let’s look at a complete example of a C function we may wish to provide to Pony. A Jump Consistent Hash, for example, could be provided in pure Pony as follows:

  1. // Jump consistent hashing in Pony, with an inline pseudo random generator
  3. fun jch(key: U64, buckets: I64): I32 =>
  4.   var k = key
  5.   var b = I64(0)
  6.   var j = I64(0)
  8.   while j < buckets do
  9.     b = j
  10.     k = (k * 2862933555777941757) + 1
  11.     j = ((b + 1).f64() * (U32(1 << 31).f64() / ((key >> 33) + 1).f64())).i64()
  12.   end
  14.   b.i32()

Let’s say we wish to compare the pure Pony performance to an existing C function with the following header:

  1. #ifndef __JCH_H_
  2. #define __JCH_H_
  4. extern "C"
  5. {
  6.   int32_t jch_chash(uint64_t key, uint32_t num_buckets);
  7. }
  9. #endif

Note the use of extern "C". If the library is built as C++ then we need to tell the compiler not to mangle the function name, otherwise, Pony won’t be able to find it. For libraries built as C, this is not needed, of course.

The implemented would be something like:

  1. #include <stdint.h>
  2. #include <limits.h>
  3. #include "math.h"
  5. // A reasonably fast, good period, low memory use, xorshift64* based prng
  6. double lcg_next(uint64_t* x)
  7. {
  8.   *x ^= *x >> 12;
  9.   *x ^= *x << 25;
  10.   *x ^= *x >> 27;
  11.   return (double)(*x * 2685821657736338717LL) / ULONG_MAX;
  12. }
  14. // Jump consistent hash
  15. int32_t jch_chash(uint64_t key, uint32_t num_buckets)
  16. {
  17.   uint64_t seed = key;
  18.   int b = -1;
  19.   int32_t j = 0;
  21.   do {
  22.     b = j;
  23.     double r = lcg_next(&seed);
  24.     j = floor((b + 1)/r);
  25.   } while(j < num_buckets);
  27.   return (int32_t)b;
  28. }

We need to compile the native code to a shared library. This example is for OSX. The exact details may vary on other platforms.

  1. clang -fPIC -Wall -Wextra -O3 -g -MM jch.c >jch.d
  2. clang -fPIC -Wall -Wextra -O3 -g   -c -o jch.o jch.c
  3. clang -shared -lm -o libjch.dylib jch.o

The Pony code to use this new C library is just like the code we’ve already seen for using C libraries.

  1. """ 
  2. This is an example of Pony integrating with native code via the built-in FFI
  3. support
  4. """
  6. use "lib:jch"
  7. use "collections"
  8. use "random"
  9. use @jch_chash[I32](hash: U64, bucket_size: U32)
  11. actor Main
  12.   var _env: Env
  14.   new create(env: Env) =>
  15.     _env = env
  17.     let bucket_size: U32 = 1000000
  18.     var random = MT
  20.     for i in Range[U64](1, 20) do
  21.       let r: U64 = random.next()
  22.       let hash = @jch_chash(i, bucket_size)
  23.       _env.out.print(i.string() + ": " + hash.string())
  24.     end

We can now use ponyc to compile a native executable integrating Pony and our C library. And that’s all we need to do.