Introduction¶
DkSDK is a set of tools to help you build native applications for the desktop, web, mobile and high-level embedded devices. One of those tools is DkSDK FFI, which is the documentation you are reading right now. The DkSDK FFI is a cross-language foreign function interface which binds the OCaml language to other "host" languages that have a Cap n' Proto binding.
Note
If you were looking for another DkSDK tool, there is:
DkSDK CMake is a tool to manage building C and OCaml source code. You can read the DkSDK CMake Introduction pages.
DkSDK FFI makes a set of trade-offs.
Its strengths are:
DkSDK FFI always allocates memory in the host language. That way the host's garbage collector, if it has one, can be used. Non-GC host languages, like C and C++, use reference counting
The data typically does not need to have one copy in the host language and a second copy in OCaml
There are only three (3) brief rules to program safely (correct object ownership, object layout, and calling convention)
Its weaknesses are:
Every function call has to be modeled with Cap n' Proto schemas. That:
can be verbose
requires a build step to translate Cap n' Proto schema into the host and OCaml languages
Unless the host language supplies a fast interface, the default reference counting implementation uses atomic operations. Atomic operations require "memory fences" which are slow on multicore machines.
Technical Details¶
DkSDK FFI uses the COM model popularized first by Microsoft for the Visual
Basic/C/Office/ soup of interoperability, and then by Apple for its Foundation
NSObject classes. COM has been working well for decades. The key elements
in the COM pattern are registering COM objects by GUID and reference counting.
DkSDK FFI COM objects come in two varieties:
Functions. For languages like C, all functions are known at compile time. However, functional languages like JavaScript and OCaml can create and delete functions at run-time, so they need some form of garbage collection (reference counting) to interact with safely
Cap n' Proto messages. Often you have functions that are asynchronous. For example, you have a GUI event that you can't handle immediately. The Cap n' Proto message stays alive until you need it. Cap n' Proto, the message protocol, is used because it has a zero-copy memory layout accessible by many languages; most other message protocols require copying memory between different languages.
DkSDK FFI has first class support for OCaml. That brings:
An interpreter or a compiler. You choose which is appropriate.
Translation to JavaScript
Safe FFI¶
Follow these rules to program safely and correctly:
Object Ownership. Choose either reference counting for long-lived shared objects, or function scope for short-lived objects
Object Layout. Follow the Cap n' Proto layout. If you need another layout, write a proxy function to change the memory layout to your own layout.
Calling Convention. Function calls are single argument, single result. If you need something else, write a proxy function to call the single arg, single result function.
Licensing¶
The platform implementations' full source code, except DkSDK FFI OCaml, is available under the commercial DkSDK Software Development Kit License Agreement. You can obtain a license on the DkSDK Pricing page.
The platform implementations' binary libraries, except DkSDK FFI C, are available on a limited number of operating systems under the OSL-3.0 open source license:
DkSDK FFI OCaml has binary libraries available for Windows, Linux and macOS.
DkSDK FFI Java has binary libraries available for 64-bit Intel/AMD Linux.
The commercial license gives you all of the supported platforms, rights to deploy and distribute your application, and freedom from the copyleft open source conditions. The open source license is sufficient to develop a prototype application on a developer machine; once you need to test and deploy your application on a mobile device or Windows or macOS, graduate to a commercial license.
