Add C Bindings to Native Client Library

To be Reviewed By:

Authors: Blake Bender

Status: Draft 

Superseded by: N/A

Related: N/A

Problem

The existing native client API is for C++ and C# only.  This is acceptable for writing client applications in C++, but presents substantial difficulties when attempting to bind to the API from any other language.  The current native client has language bindings for C# via the Microsoft "IJW" language, a.k.a. C++/CLI, which Microsoft has subsequently abandoned, more-or-less.  The .net framework has also subsequently been deprecated in favor of .net core, which has even less support for IJW than the original framework.  The preferred way to interface with C/C++ libraries for .net core, along with many, many other languages, is via C bindings.  I propose to add these to the native client, starting with the most basic functionality, and working towards eventually supporting the entire existing API.

Anti-Goals

This proposal is strictly limited to adding C bindings to the native client. We do not wish to make any specific proposals for supporting Geode access via any other languages (.net core, Python, etc) here.

Solution

A simple C binding for a native client library function would look something like this:

APACHE_GEODE_EXPORT void* CreateCacheFactory();

And be implemented something like this:

void* CreateCacheFactory() {
  CacheFactoryWrapper* cacheFactory = new CacheFactoryWrapper();
  return cacheFactory;
}

Binding to this function and calling it is trivial for most other languages. Here's an example for .net core:

[DllImport(Constants.libPath, CharSet = CharSet.Auto)]

private static extern IntPtr CreateCacheFactory();

var containedObject = CreateCacheFactory();

And from Python:

from ctypes import cdll, c_void_p

nativeclient_ = cdll.LoadLibrary(
   "/Users/build/Workspace/native_client_install/libpivotal-gemfire.dylib"
)

nativeclient_.CreateCacheFactory.restype = c_void_p

nativeclient_.DestroyCacheFactory.argtypes = [c_void_p]

factory_ = self.nativeclient_.CreateCacheFactory()

Other languages follow a similar pattern. 

Changes and Additions to Public Interfaces

We propose to add C bindings of a form similar to the above to the public API for the native client.  The new API would need to be fully documented, but we believe implementation can start with coverage of a very small subset of the existing C++ API and still be extremely useful.

Performance Impact

Any performance impact of calling through a C binding should be very minimal.  A C function exposing a native client method should only involve a pointer cast and a call to the "wrapped" C++ API.  Additionally, there will be no performance impact whatsoever for existing applications, since we're not proposing to modify any of the existing C++ code.  Eventually we should be able to benchmark the C vs C++ calls to quantify the performance difference, but this is a fairly low priority.  Benchmarking API performance from another language calling through the C bindings is a much more interesting and necessary task, which we believe will be undertaken as part of any future support for said language.

Backwards Compatibility and Upgrade Path

Since this is entirely new functionality, and makes no modification to existing APIs, there is no backwards compatibility burden to be considered here. 

Prior Art

C bindings allow a client written in C to access the native client directly, but primarily they are interesting because they allow easy access to the API from a much larger overall set of (non-C) languages.  One other alternative to access Geode from another language is to provide a full implementation of the Geode wire protocol in that language.  At the moment, this is a very large undertaking, because the Geode protocol is complex, and not fully documented outside of the existing implementations in Geode and the Java and native clients.  Another alternative would be to define an entirely new protocol via some language or tooling that would allow us to generate bindings for different languages.  Google's protobuf, for instance, provides this functionality.  Unfortunately, this is an even taller order than either of the first two options, since it involves fairly extensive modification of the server code, in addition to the clients.  We believe the simple C bindings proposed provide a workable solution for many languages and applications which can be completed in a reasonable time frame.

FAQ

Errata