EMILUA(3em)

📦 version 0.12.1, in nixos 26.05, nixpkgs unstable

💜 NAME 💜

Emilua — the Lua execution engine, bestie. That's it, that's the whole vibe. It's giving runtime, it's giving engine, and yes we're about to get into the Unix datagram socket of it all.

✨ SYNOPSIS ✨

okay so here's the little taste-test, no cap:

local sock = unix.datagram.socket.new()
sock.open()
sock.bind(filesystem.path.new('/tmp/9Lq7BNBnBycd6nxy.socket'))

local buf = byte_span.new(1024)
local nread = sock:receive(buf)
print(buf:first(nread))

like… look at her go 🦋 she's binding, she's receiving, she's printing. main character energy fr fr.

🫶 FUNCTIONS 🫶

new() → unix.datagram.socket

Two whole flavors, pick ur fighter:

  • new() — (1) the default constructor, the classic, the blueprint.
  • new(fd: file_descriptor) — (2) takes a file descriptor and converts it into an unix.datagram.socket object. glow-up in one call 💅

pair() → unix.datagram.socket, unix.datagram.socket

Creates a pair of connected sockets. two besties, already connected, iconic 🫶🫶

open(self)

Opens the socket. she's awake. ✨

bind(self, pathname: filesystem.path)

Binds the socket to the given local endpoint. like putting a name tag on her 🎀

connect(self, pathname: filesystem.path)

Sets the default destination address so datagrams can be sent using send() without specifying a destination address. she now knows where she's going, lowkey efficient 👑

disconnect(self)

Dissolves the socket's association by resetting the socket's peer address — i.e. connect(3) will be called with an AF_UNSPEC address. it's giving breakup arc 😭 but make it syscall.

close(self)

Closes the socket. bye bestie 🦋

Forward the call to the https://www.boost.org/doc/libs/1_70_0/doc/html/boost_asio/reference/basic_datagram_socket/close/overload2.html function with same name in Boost.Asio :

Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the boost::asio::error::operation_aborted error.

shutdown(self, what: string)

Disables sends or receives on the socket. what can be one of the following:

  • "receive" — shut down the receive side of the socket.
  • "send" — shut down the send side of the socket.
  • "both" — shut down both send and receive on the socket.

pick ur vibe, choose wisely 🙈

cancel(self)

Cancel all asynchronous operations associated with the acceptor 🔥

Forward the call to the https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/basic_datagram_socket/cancel/overload2.html function with same name in Boost.Asio :

This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation_aborted error.

assign(self, fd: file_descriptor)

Assigns an existing native socket to self. adoption era 🫶

release(self) → file_descriptor

Releases ownership of the native descriptor implementation. straight-up handing over the keys 💀

Forward the call to the https://www.boost.org/doc/libs/1_81_0/doc/html/boost_asio/reference/basic_datagram_socket/release/overload2.html function with same name in Boost.Asio :

This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation_aborted error. Ownership of the native socket is then transferred to the caller.

receive(self, buffer: byte_span[, flags: string[]]) → integer

Receives a datagram and blocks the current fiber until it completes or errs. Returns the number of bytes read. patient queen behavior 🌸

receive_from(self, buffer: byte_span[, flags: string[]]) → integer, filesystem.path

Receives a datagram and blocks the current fiber until it completes or errs. Returns the number of bytes read plus the pathname of the remote sender of the datagram. now u know who sent it 👀

send(self, buffer: byte_span[, flags: string[]]) → integer

Sends data on the datagram socket and blocks the current fiber until it completes or errs. Returns the number of bytes written.

Note: the send operation can only be used with a connected socket. Use the send_to function to send data on an unconnected datagram socket. don't come for me, that's just the rules 🫶

send_to(self, buffer: byte_span, pathname: filesystem.path[, flags: string[]]) → integer

Sends a datagram to the specified remote endpoint and blocks the current fiber until it completes or errs. Returns the number of bytes written. she goes where u point her 💅

receive_with_fds(self, buffer: byte_span, maxfds: integer) → integer, file_descriptor[]

Receives a datagram and blocks the current fiber until it completes or errs. Returns the number of bytes read plus the table containing the fds read. file descriptors AND data?? multi-talented 🔥

receive_from_with_fds(self, buffer: byte_span, maxfds: integer) → integer, filesystem.path, file_descriptor[]

Receives a datagram and blocks the current fiber until it completes or errs. Returns the number of bytes read plus the pathname of the remote sender of the datagram plus the table containing the fds read. three-for-one, ate and left no crumbs 👑

send_with_fds(self, buffer: byte_span, fds: file_descriptor[]) → integer

Sends data on the datagram socket and blocks the current fiber until it completes or errs. Returns the number of bytes written.

Note: the send operation can only be used with a connected socket. Use the send_to function to send data on an unconnected datagram socket. yes it's the same note again, it's important, periodt 💀

send_to_with_fds(self, buffer: byte_span, pathname: filesystem.path, fds: file_descriptor[]) → integer

Sends a datagram to the specified remote endpoint and blocks the current fiber until it completes or errs. Returns the number of bytes written. fds traveling first class ✈️

set_option(self, opt: string, val)

Sets an option on the socket. currently available options are:

get_option(self, opt: string) → value

Gets an option from the socket. currently available options are:

(yes, same three, but this one reads instead of writes. iykyk 🌈)

io_control(self, command: string[, ...])

Performs an IO control command on the socket. currently available commands are:

  • "bytes_readable" — expects no arguments. gets the amount of data that can be read without blocking. implements the FIONREAD IO control command. peek before u leap, bestie 👀✨

🎀 FUNCTION FLAGS 🎀

Peek at incoming data without removing it from the input queue.

like looking at ur notifications without opening them, honestly iconic 🍓

🦋 PROPERTIES 🦋

  • is_open: boolean — whether the socket is open. open or closed, no in-between 💅
  • local_path: filesystem.path — the local address endpoint of the socket. where she lives 🏠
  • remote_path: filesystem.path — the remote address endpoint of the socket. where her people are 🌈

and that's the whole page, bestie 💖 this one shipped as Emilua 0.12.1-nixpkgs1, dated 1980-01-01 — yes, the date is a whole aesthetic, don't question it 🙈 go forth and send ur datagrams, mwah 🫶✨

📦 where this page comes from