omq_gleam
Gleam API for OMQ.
OMQ sockets are ZeroMQ-compatible message queues backed by the Rust
omq-tokio runtime. Create a context with context or reuse the
process-wide singleton with context_instance, then create sockets with
socket.
Endpoints are UTF-8 bit arrays such as <<“tcp://127.0.0.1:5555”:utf8>>, <<“ipc:///tmp/omq.sock”:utf8>>, <<“inproc://queue”:utf8>>, <<“lz4+tcp://127.0.0.1:5555”:utf8>>, and <<“zstd+tcp://127.0.0.1:5555”:utf8>>.
Functions return Ok(value) or Error(#(class, reason)) unless they are
pure constants or feature checks. send and recv move binary frames;
string, JSON, term, multipart, pub/sub, RADIO/DISH, and socket option
helpers wrap the Erlang base package.
Types
Opaque connection snapshot map from Erlang.
pub type ConnectionInfoOpaque monitor event map from Erlang.
pub type MonitorEventValues
pub fn backend_name() -> Result(BitArray, #(String, String))Return native backend name.
pub fn bind(
socket: Socket,
endpoint: BitArray,
) -> Result(BitArray, #(String, String))Bind socket to endpoint and return bound endpoint.
pub fn bind_to_random_port(
socket: Socket,
addr: BitArray,
min_port: Int,
max_port: Int,
) -> Result(Int, #(String, String))Bind socket to random port in inclusive range.
pub fn close(socket: Socket) -> Result(Nil, #(String, String))Close socket with zero linger.
pub fn configure_plain_server(
socket: Socket,
credentials: List(#(BitArray, BitArray)),
) -> Result(Nil, #(String, String))Configure an exact, case-sensitive PLAIN server credential allowlist.
Call before bind, connect, send, or receive. Each username and password must contain at most 255 ASCII VCHAR bytes. An empty list rejects every client. PLAIN authenticates clients but does not encrypt traffic.
pub fn connect(
socket: Socket,
endpoint: BitArray,
) -> Result(Nil, #(String, String))Connect socket to endpoint.
pub fn connection_info(
socket: Socket,
connection_id: Int,
) -> Result(ConnectionInfo, #(String, String))Return one connection snapshot by ID.
pub fn connections(
socket: Socket,
) -> Result(List(ConnectionInfo), #(String, String))Return current connection snapshots for socket.
pub fn context() -> Result(Context, #(String, String))Create a context with one IO thread.
pub fn context_closed(context: Context) -> BoolReturn whether context wrapper or native core is closed.
pub fn context_from_share_key(
share_key: Int,
) -> Result(Context, #(String, String))Import native context by share key.
pub fn context_instance() -> Result(Context, #(String, String))Return process-wide singleton context.
pub fn context_instance_with_io_threads(
io_threads: Int,
) -> Result(Context, #(String, String))Return process-wide singleton context, creating it with IO thread count.
pub fn context_share_key(
context: Context,
) -> Result(Int, #(String, String))Return opaque native context share key.
pub fn curve_keypair() -> Result(
#(BitArray, BitArray),
#(String, String),
)Generate CURVE public/secret keypair.
pub fn curve_public(
secret: BitArray,
) -> Result(BitArray, #(String, String))Derive CURVE public key from secret key.
pub fn destroy(
context: Context,
) -> Result(Nil, #(String, String))Terminate a context. Alias for term.
pub fn device(
device_type: Int,
frontend: Socket,
backend: Socket,
) -> Result(Nil, #(String, String))Run libzmq-compatible device. Device type is accepted for parity.
pub fn disconnect(
socket: Socket,
endpoint: BitArray,
) -> Result(Nil, #(String, String))Disconnect socket from endpoint.
pub fn from_share_key(
share_key: Int,
) -> Result(Context, #(String, String))Import native context by share key.
pub fn get_hwm(socket: Socket) -> Result(Int, #(String, String))Return SNDHWM as compatibility HWM value.
pub fn getsockopt_binary(
socket: Socket,
option: Int,
) -> Result(BitArray, #(String, String))Get binary socket option.
pub fn getsockopt_int(
socket: Socket,
option: Int,
) -> Result(Int, #(String, String))Get integer socket option.
pub fn getsockopt_string(
socket: Socket,
option: Int,
) -> Result(String, #(String, String))Get binary socket option as UTF-8 string.
pub fn has(capability: BitArray) -> BoolReturn whether native feature or transport is available.
pub fn instance() -> Result(Context, #(String, String))Return process-wide singleton context.
pub fn instance_with_io_threads(
io_threads: Int,
) -> Result(Context, #(String, String))Return process-wide singleton context, creating it with IO thread count.
pub fn join(
socket: Socket,
group: BitArray,
) -> Result(Nil, #(String, String))Join RADIO/DISH group.
pub fn leave(
socket: Socket,
group: BitArray,
) -> Result(Nil, #(String, String))Leave RADIO/DISH group.
pub fn monitor(
socket: Socket,
) -> Result(Monitor, #(String, String))Create monitor stream for socket lifecycle events.
pub fn monitor_recv(
monitor: Monitor,
timeout_ms: Int,
) -> Result(MonitorEvent, #(String, String))Receive next monitor event with timeout in milliseconds.
pub fn monitor_try_recv(
monitor: Monitor,
) -> Result(MonitorEvent, #(String, String))Try to receive one monitor event without blocking.
pub fn omq_compression_auto_train() -> IntReturn OMQ_COMPRESSION_AUTO_TRAIN constant.
pub fn omq_compression_level() -> IntReturn OMQ_COMPRESSION_LEVEL constant.
pub fn omq_on_mute_drop_newest() -> IntReturn OMQ_ON_MUTE drop-newest mode value.
pub fn omq_on_mute_drop_oldest() -> IntReturn OMQ_ON_MUTE drop-oldest mode value.
pub fn omq_version() -> Result(BitArray, #(String, String))Return native binding version. Alias for version.
pub fn omq_version_info() -> Result(
#(Int, Int, Int),
#(String, String),
)Return native binding version as #(major, minor, patch).
pub fn proxy(
frontend: Socket,
backend: Socket,
) -> Result(Nil, #(String, String))Run bidirectional proxy between two sockets.
pub fn proxy_steerable(
frontend: Socket,
backend: Socket,
capture: Socket,
control: Socket,
) -> Result(Nil, #(String, String))Run steerable proxy with PAUSE, RESUME, and TERMINATE control.
pub fn proxy_with_capture(
frontend: Socket,
backend: Socket,
capture: Socket,
) -> Result(Nil, #(String, String))Run proxy and mirror traffic to capture socket.
pub fn recv(
socket: Socket,
) -> Result(BitArray, #(String, String))Receive one binary message.
pub fn recv_frame(
socket: Socket,
) -> Result(BitArray, #(String, String))Receive next frame from multipart message.
pub fn recv_json(
socket: Socket,
) -> Result(dynamic.Dynamic, #(String, String))Receive one JSON value decoded by OTP json.
pub fn recv_multipart(
socket: Socket,
) -> Result(List(BitArray), #(String, String))Receive one multipart message.
pub fn recv_string(
socket: Socket,
) -> Result(String, #(String, String))Receive one UTF-8 string message.
pub fn recv_string_timeout(
socket: Socket,
timeout_ms: Int,
) -> Result(String, #(String, String))Receive one string with timeout in milliseconds.
pub fn recv_term(
socket: Socket,
) -> Result(dynamic.Dynamic, #(String, String))Receive one Erlang term encoded by send_term.
pub fn send(
socket: Socket,
data: BitArray,
) -> Result(Nil, #(String, String))Send one binary message.
pub fn send_group(
socket: Socket,
group: BitArray,
body: BitArray,
) -> Result(Nil, #(String, String))Send RADIO message to group.
pub fn send_json(
socket: Socket,
value: dynamic.Dynamic,
) -> Result(Nil, #(String, String))Send one JSON value encoded by OTP json.
pub fn send_multipart(
socket: Socket,
parts: List(BitArray),
) -> Result(Nil, #(String, String))Send one multipart message.
pub fn send_string(
socket: Socket,
text: String,
) -> Result(Nil, #(String, String))Send one UTF-8 string message.
pub fn send_term(
socket: Socket,
term: dynamic.Dynamic,
) -> Result(Nil, #(String, String))Send one Erlang term using external term format.
pub fn set_hwm(
socket: Socket,
value: Int,
) -> Result(Nil, #(String, String))Set both SNDHWM and RCVHWM.
pub fn setsockopt_binary(
socket: Socket,
option: Int,
value: BitArray,
) -> Result(Nil, #(String, String))Set binary socket option.
pub fn setsockopt_int(
socket: Socket,
option: Int,
value: Int,
) -> Result(Nil, #(String, String))Set integer socket option.
pub fn setsockopt_string(
socket: Socket,
option: Int,
value: String,
) -> Result(Nil, #(String, String))Set binary socket option from UTF-8 string.
pub fn share_key(
context: Context,
) -> Result(Int, #(String, String))Return opaque native context share key.
pub fn socket(
context: Context,
socket_type: Int,
) -> Result(Socket, #(String, String))Create socket from context and socket type constant.
pub fn socket_id(
socket: Socket,
) -> Result(Int, #(String, String))Return wrapper socket ID.
pub fn socket_type(
socket: Socket,
) -> Result(String, #(String, String))Return socket type atom name as string.
pub fn strerror(errno: Int) -> BitArrayReturn POSIX strerror text for common libzmq errno values.
pub fn subscribe(
socket: Socket,
prefix: BitArray,
) -> Result(Nil, #(String, String))Subscribe SUB or XSUB socket to prefix.
pub fn try_recv(
socket: Socket,
) -> Result(BitArray, #(String, String))Try to receive one binary message without blocking.
pub fn try_recv_json(
socket: Socket,
) -> Result(dynamic.Dynamic, #(String, String))Try to receive one JSON value without blocking.
pub fn try_recv_multipart(
socket: Socket,
) -> Result(List(BitArray), #(String, String))Try to receive one multipart message without blocking.
pub fn try_recv_string(
socket: Socket,
) -> Result(String, #(String, String))Try to receive one UTF-8 string without blocking.
pub fn try_recv_term(
socket: Socket,
) -> Result(dynamic.Dynamic, #(String, String))Try to receive one Erlang term without blocking.
pub fn unbind(
socket: Socket,
endpoint: BitArray,
) -> Result(Nil, #(String, String))Unbind socket from endpoint.
pub fn unsubscribe(
socket: Socket,
prefix: BitArray,
) -> Result(Nil, #(String, String))Remove SUB or XSUB prefix subscription.
pub fn wait_connected(
socket: Socket,
min_peers: Int,
timeout_ms: Int,
) -> Result(Int, #(String, String))Wait until minimum peer count is connected.
pub fn wait_subscribed(
socket: Socket,
min_subscriptions: Int,
timeout_ms: Int,
) -> Result(Int, #(String, String))Wait until minimum subscription generation is visible.
pub fn zmq_version_info() -> #(Int, Int, Int)Return libzmq compatibility version tuple.