Unifex - same code for NIFs and C nodes

Hello everyone,

pleased to announce Unifex, a tool that simplifies integrating elixir with C/C++. Unifex has been out for some time already but since v0.3 released today, it supports generating C nodes - lightweight programs acting as Erlang nodes. Though communication with NIFs is way faster than with separate nodes, a failing node doesn’t crash the entire VM, moreover, it can be supervised like a normal process. Unifex allows choosing between NIFs and C nodes at any point, even in runtime.

Approach

Here are some key facts about Unifex:

  • Native code is kept separate from elixir code
  • Native code doesn’t depend on erlang libraries, but on Unifex abstraction, that aims to be more user friendly than erlang APIs
  • Unifex works by generating boilerplate code in the compile-time, based on DSL in elixir
  • Unifex aims to support the intersection of sets of data types from Elixir and C
  • Unifex relies on Bundlex, our tool for compiling native code

Here’s how it looks like in short: firstly, you describe the interface with spec-like DSL:

module Example

interface [NIF, CNode]

spec foo(num :: int) :: {:ok :: label, answer :: int}

then you provide implementation:

#include "_generated/example.h"

UNIFEX_TERM foo(UnifexEnv* env, int num) {
  return foo_result_ok(env, num);
}

and finally, you use it either as NIF

defmodule Example do
  use Unifex.Loader
end
iex> Example.foo(10)
{:ok, 10}

or as CNode

iex> require Unifex.CNode
iex> {:ok, cnode} = Unifex.CNode.start_link(:example)
iex> Unifex.CNode.call(cnode, :foo, [10])
{:ok, 10}

A detailed description of how to place that in a Mix project can be found here.

Use cases

We’re using Unifex heavily at Membrane, mainly for wrapping some complex, stateful libs, and that’s where Unifex suits the most IMHO.

Status

Though we’ve been using Unifex for NIFs for some time, adding C nodes required lots of changes that are quite fresh. We’re validating them while developing Membrane ICE plugin.

Feedback and contributions are most welcome :wink:

Credits: @Feliks, @mickel8, @bblaszkow06, @mkaput, Software Mansion

10 Likes

Unifex v0.4.0 released :tada:

This version adds the ability to define custom types and use them in Unifex specs. For now, enums and structs are supported. Declaring them generates C enums and C structs, respectively, for example:

type position :: :manager | :developer | :intern | :product_owner

type personal_data :: %PersonalData{
  age: int,
  expirience: int,
  name: string
}

will generate

enum Position_t { MANAGER, DEVELOPER, INTERN, PRODUCT_OWNER };
typedef enum Position_t Position;

struct personal_data_t {
  int age;
  int expirience;
  char *name;
};
typedef struct personal_data_t personal_data;

and can be used like

spec get_salary(person :: personal_data, person_position :: position) ::
       {:ok :: label, salary :: int}
       | {:error :: label, :unemployed :: label}

Docs, GitHub

Credits go to @Feliks, thanks!

5 Likes