[erlang-questions] The "ei" API and passing *shared* binaries / parts

[Vance Shipley]

On Fri, Jun 30, 2017 at 12:51 PM, Rick van Rein <rick@REDACTED> wrote:
> what seems to be needed to share blobs would apparently be
>
>  0. Have a blob uint8_t ptr [siz]
>  1. Create an ETERM for it with erl_mk_binary (ptr, siz)
>  2. Send with ei_encode_term
>  3. Update refctr / free if needed (docs are not clear)

The most efficient and flexible way to integrate C libraries with
Erlang is to write a linked in driver which allows sharing processing
between C and Erlang, passing the data back and forth as required.
I've written a bunch of drivers over the years. If you need help
figuring any of this out just ask but the following should get you on
the right track.

The erl_driver C library API is described here:
   http://erlang.org/doc/man/erl_driver.html
   http://erlang.org/doc/man/driver_entry.html

A driver creates a binary erlang term with driver_alloc_binary():
   http://erlang.org/doc/man/erl_driver.html#driver_alloc_binary

A driver may send a binary to an erlang port with driver_output_binary():
   http://erlang.org/doc/man/erl_driver.html#driver_output_binary

A driver should use erl_drv_output_term() to send erlang terms to the
port owner:
   http://erlang.org/doc/man/erl_driver.html#erl_drv_output_term

An erlang process may use port_command/2 to send iodata() which a
driver receives in it's outputv() calback:
   http://erlang.org/doc/man/erlang.html#port_command-2
   http://erlang.org/doc/man/driver_entry.html#outputv

The data received in outputv() is an ErlIOVec structure:
   http://erlang.org/doc/man/erl_driver.html#ErlIOVec

An erlang process may use port_call/3 to send arbitrary terms which a
driver receives in it's call() callback:
   http://erlang.org/doc/man/erlang.html#port_call-3
   http://erlang.org/doc/man/driver_entry.html#call

The data received in call() is Erlang external term format which can
be decoded with a series of calls to ei_decode_*():
   http://erlang.org/doc/man/ei.html

If you only need to call C library functions from Erlang and get an
immediate result you may write a NIF instead of a full linked in
driver:
   http://erlang.org/doc/tutorial/nif.html
   http://erlang.org/doc/man/erl_nif.html




-- 
     -Vance