py_byte_channel (erlang_python v3.0.0)

View Source

Raw byte channel for Erlang-Python communication.

ByteChannel provides raw byte streaming without term serialization, suitable for HTTP bodies, file transfers, and binary protocols.

Unlike py_channel which serializes Erlang terms, ByteChannel passes raw binaries directly without any encoding/decoding overhead.

Usage

   %% Create a byte channel
   {ok, Ch} = py_byte_channel:new(),
  
   %% Send raw bytes to Python
   ok = py_byte_channel:send(Ch, <<"HTTP/1.1 200 OK\r\n">>),
  
   %% Python receives via ByteChannel.receive_bytes()
   %% Python sends back via ByteChannel.send_bytes()
  
   %% Close when done
   py_byte_channel:close(Ch).

When to Use

  • HTTP request/response bodies
  • File streaming
  • Binary protocols without Erlang term overhead

Summary

Types

channel/0
opts/0

Functions

close(Channel)

Close a byte channel.

info(Channel)

Get channel information.

new()

Create a new byte channel with default settings.

new(Opts)

Create a new byte channel with options.

recv(Channel)

Receive raw bytes from a channel (blocking).

recv(Channel, Timeout)

Receive raw bytes from a channel with timeout.

register_callbacks()

Register byte channel callback handlers for Python.

send(Channel, Bytes)

Send raw bytes to a channel.

try_receive(Channel)

Try to receive raw bytes from a channel (non-blocking).

Types

channel/0

-type channel() :: reference().

opts/0

-type opts() :: #{max_size => non_neg_integer()}.

Functions

close(Channel)

-spec close(channel()) -> ok.

Close a byte channel.

Signals Python receivers that no more bytes will arrive.

info(Channel)

-spec info(channel()) -> map().

Get channel information.

Returns a map with:

  • size - Current queue size in bytes
  • max_size - Maximum queue size (0 = unlimited)
  • closed - Whether the channel is closed

new()

-spec new() -> {ok, channel()} | {error, term()}.

Create a new byte channel with default settings.

Creates an unbounded channel for raw byte passing.

new(Opts)

-spec new(opts()) -> {ok, channel()} | {error, term()}.

Create a new byte channel with options.

Options:

  • max_size - Maximum queue size in bytes for backpressure (0 = unlimited)

recv(Channel)

-spec recv(channel()) -> {ok, binary()} | {error, closed | term()}.

Receive raw bytes from a channel (blocking).

Blocks until data is available. Equivalent to recv(Channel, infinity).

recv(Channel, Timeout)

-spec recv(channel(), timeout()) -> {ok, binary()} | {error, closed | timeout | term()}.

Receive raw bytes from a channel with timeout.

Blocks until data is available or timeout expires.

register_callbacks()

-spec register_callbacks() -> ok.

Register byte channel callback handlers for Python.

This should be called during application startup to enable Python's erlang.call('_py_byte_channel_receive', ...) etc.

send(Channel, Bytes)

-spec send(channel(), binary()) -> ok | busy | {error, term()}.

Send raw bytes to a channel.

The binary is queued directly for Python to receive without any term serialization. If the queue exceeds max_size, returns busy (backpressure).

try_receive(Channel)

-spec try_receive(channel()) -> {ok, binary()} | {error, empty | closed | term()}.

Try to receive raw bytes from a channel (non-blocking).

Returns immediately with binary data or empty/closed status.