# `Bundlex.CNode`
[🔗](https://github.com/membraneframework/bundlex/blob/v1.5.8/lib/bundlex/cnode.ex#L1)

Utilities to ease interaction with Bundlex-based CNodes, so they can be treated
more like Elixir processes / `GenServer`s.

# `on_start_t`

```elixir
@type on_start_t() :: {:ok, t()} | {:error, :spawn_cnode | :connect_to_cnode}
```

# `t`

```elixir
@type t() :: %Bundlex.CNode{node: node(), server: pid()}
```

Reference to the CNode.

Consists of pid of CNode's associated server and CNode name.

# `call`

```elixir
@spec call(t(), message :: term(), timeout :: non_neg_integer() | :infinity) ::
  response :: term()
```

Makes a synchronous call to CNode and waits for its reply.

The CNode is supposed to send back a `{cnode, response}` tuple where `cnode`
is the node name of CNode. If the response doesn't come in within `timeout`,
error is raised.

Messages are exchanged directly (without interacting with CNode's associated
server).

# `monitor`

```elixir
@spec monitor(t()) :: reference()
```

Starts monitoring CNode from the calling process.

# `send`

```elixir
@spec send(t(), message :: term()) :: :ok
```

Sends a message to cnode.

The message is exchanged directly (without interacting with CNode's associated
server).

# `start`
*macro* 

Spawns and connects to CNode `cnode_name` from application of calling module.

See `Bundlex.CNode.start/2` for more details.

# `start`

```elixir
@spec start(app :: atom(), native_name :: atom()) :: on_start_t()
```

Works the same way as `start_link/2`, but does not link to CNode's associated
server.

# `start_link`
*macro* 

Spawns and connects to CNode `cnode_name` from application of calling module.

See `Bundlex.CNode.start_link/2` for more details.

# `start_link`

```elixir
@spec start_link(app :: atom(), native_name :: atom()) :: on_start_t()
```

Spawns and connects to CNode `cnode_name` from application `app`.

The CNode is passed the following command line arguments:
- host name,
- alive name,
- node name,
- creation number.

After CNode startup, these parameters should be passed to
[`ei_connect_xinit`](http://erlang.org/doc/man/ei_connect.html#ei_connect_xinit)
function, and CNode should be published and await connection. Once the CNode is
published, it should print a line starting with `ready` to the standard output
**and flush the standard output** to avoid the line being buffered.

Under the hood, this function starts an associated server, which is responsible
for monitoring the CNode and monitoring calling process to be able to do proper
cleanup upon a crash. On startup, the server does the following:
1. Makes current node distributed if it is not done yet (see `Node.start/2`).
1. Assigns CNode a unique name.
1. Starts CNode OS process using `Port.open/2`.
1. Waits (at most 5 seconds) until a line `ready` is printed out
(this line is captured and not forwarded to the stdout).
1. Connects to the CNode.

The erlang cookie is passed using the BUNDLEX_ERLANG_COOKIE an environment variable.

# `stop`

```elixir
@spec stop(t()) :: :ok | {:error, :disconnect_cnode}
```

Disconnects from CNode.

It is the responsibility of the CNode to exit upon connection loss.

---

*Consult [api-reference.md](api-reference.md) for complete listing*