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 all local-evaluation experiment SDKs.

The current implementation supports:
JVM
Node.js
Native
- macos
  - macosX64
  - macosArm64
- linux
  - linuxX64
  - linuxArm64

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;
}

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

`evaluation-serialization`

Module containing kotlinx serialization annotated objects and mapping functions for equivalent objects in evaluation-core. Core objects are not annotated in order to optimize JavaScript generated code size.

This module is used by evaluation-interop and experiment-jvm-server to add serialization to flag configs and user objects. This package is not supposed to be used externally.

`evaluation-js`

Module which only targets nodejs, optimizing bundle size and evaluation speed and consistency. The generated javascript is completely stateless, and takes and returns dynamic javascript objects/arrays in the evaluate function.

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

amplitude / experiment-evaluation Goto Github PK