experiment-evaluation

Multiplatform (JVM, Node.js, Native) implementation of the experiment evaluation engine. The purpose of this library is to share the same evaluation code across local-evaluation experiment SDKs which don't have a language-native implementation (Ruby, Python).

• The current implementation supports:
• JVM
• Native
  • macos
    • macosX64
    • macosArm64
  • linux
    • linuxX64
    • linuxArm64

Used in:

• experiment-ruby-server
• experiment-python-server

Build

This may take some time.

./gradlew assemble

Modules

evaluation-core

The core evaluation engine with public data types exposed. Used by other kotlin mulitplatform modules/libraries and JVM targets. This code is pure multiplatform kotlin, without any dependencies.

evaluation-interop

Module which supports better interoperability with native targets. Uses kotlinx serialization to serialize data across the native interface.

This module exposes a single function evaluate which takes JSON String inputs and outputs. The caller is in charge of building the json objects and parsing the result.

fun evaluate(rules: String, user: String): String

This kotlin function maps to an equivalent function in C:

const char* (*evaluate)(const char* rules, const char* user);

This string returned from the call to evaluate must be freed by calling the DisposeString utility function.

void (*DisposeString)(const char* string);

These functions are wrapped in structures generated by kotlin (some functions omitted):

typedef struct {
  /* Dispose string function. */
  void (*DisposeString)(const char* string);

  /* User functions. */
  struct {
    struct {
      /* Evaluate function. */
      const char* (*evaluate)(const char* rules, const char* user);
    } root;
  } kotlin;
} libevaluation_interop_ExportedSymbols;
extern libevaluation_interop_ExportedSymbols* libevaluation_interop_symbols(void);

Here's a full example of calling evaluate, then DisposeString in C:

#include "libevaluation_interop_api.h"
#include "stdio.h"

int main(int argc, char** argv) {
    libevaluation_interop_ExportedSymbols* lib = libevaluation_interop_symbols();

    const char* rules = "{}";
    const char* user = "{}";
    
    const char* response = lib->kotlin.root.evaluate(rules, user);
    printf("%s\n", response);
    lib->DisposeString(response);

    return 0;
}

Important Build Outputs

Native static and dynamic libraries are built for specific operating systems and architectures. For dynamic libraries, MacOS targets generate .dylib files while linux targets generate .so files. Outputs are generated for debug and release build flavors. Debug flavor outputs will contain additional debug info when the native code crashes (kotlin stack traces, register dump, etc).

• <target>
  • macosX64: MacOS with Intel Chip
  • macosArm64: MacOS with M1 / Apple Silicon Chip
  • linuxX64: Linux with Intel/AMD (x64)
  • linuxArm64: Linux with Arm Chip
• <flavor>
  • debug: larger, slower binaries with additional debug output on crash (stack traces, register dump, etc.)
  • release: smaller, faster binaries without additional debug output on crash.
• <file>
  • dylib: output file type for macOS
  • so: output file type for linux

# Dynamic Libraries
build/bin/<target>/<flavor>Shared/libevaluation_interop.<file>
build/bin/<target>/<flavor>Shared/libevaluation_interop_api.h

# Static Libraries
build/bin/<target>/<flavor>Static/libevaluation_interop.a
build/bin/<target>/<flavor>Static/libevaluation_interop_api.h