BeamQN

An experiment in linking CBQN into the Erlang BEAM as a NIF.

Status

BeamQN is experimental software and is not ready for production use. Use at your own risk!

The risks of using this library include, but are not limited to:

• Memory leaks
• Scheduler collapse
• Undefined behavior
• System crash

In order to rapidly identify bugs, it is recommended to develop BeamQN applications using a debug enabled Erlang runtime system. A general guide for building a debug enabled Erlang runtime system and the latest Rebar3 build tool is below.

Usage

Eshell V14.2.1 (press Ctrl+G to abort, type help(). for help)
1> {ok, F} = beamqn:eval(<<"+"/utf8>>),
   {ok, X} = beamqn:make([1,2,3]),
   {ok, W} = beamqn:make([4,5,6]),
   {ok, R} = beamqn:call(F,{X,W}),
   beamqn:read(R).
{ok,[5,7,9]}

Build (Development)

1. Download and extract the latest Erlang/OTP release tarball from the downloads page.
2. Export $ERL_TOP to the path of the extracted source.
3. Build Erlang/OTP from the release tarball.
4. Build the debug enabled runtime system.
5. Install Rebar3 from source using the latest Erlang/OTP release tarball.

env PATH=$ERL_TOP:$PATH ./bootstrap

7. Export $REBAR_TOP to the path of the rebar3 source.

8. Using the compiled runtime for development:

   Debug

   env PATH=$ERL_TOP/bin:$PATH $REBAR_TOP/rebar3 compile
   env PATH=$ERL_TOP/bin:$PATH cerl -debug +pc unicode -pa ebin -pa ./_build/default/lib/*/ebin
   

Installation (Erlang)

The package can be installed by adding beamqn to your list of dependencies in rebar.config:

{deps, [
    {beamqn, {git, "https://github.com/cannadayr/BeamQN.git", {branch, "main"}}}
]}.

Installation (Elixir)

The package can be installed by adding beamqn to your list of dependencies in mix.exs:

def deps do
  [
    {:beamqn, git: "https://github.com/cannadayr/BeamQN.git", branch: "main"}
  ]
end

Documentation

Documentation can be generated with EDoc.

env PATH=$ERL_TOP/bin:$PATH $REBAR_TOP/rebar3 edoc

Once generated, the docs can be found at /doc/.

Testing

Tests can be ran with EUnit.

env PATH=$ERL_TOP/bin:$PATH $REBAR_TOP/rebar3 eunit