EMILUA(3em)

📦 version 0.12.1, in nixos 26.05, nixpkgs unstable

okay so bestie, welcome to EMILUA(3em) from the Emilua reference manual — it's literally the Lua execution engine page and I'm obsessed 💅✨

🌸 NAME 🌸

Emilua - Lua execution engine. that's the whole vibe, short and iconic 🦋

✨ SYNOPSIS ✨

here's the little starter snack, no cap:

local sock = ip.udp.socket.new()
sock.open('v4')
sock:bind(ip.address.any_v4(), 1234)

local buf = byte_span.new(1024)
local nread, remote_addr, remote_port = sock:receive_from(buf)
sock:send_to(buf:first(nread), remote_addr, remote_port)

💅 FUNCTIONS 💅

okay so here's the whole roster, every single one, we don't skip 💖

🎀 new() → ip.udp.socket

Constructor. literally just makes the thing ✨

new() → ip.udp.socket

🎀 open(self, address_family: v4"|"v6"|ip.address)"

Open the socket. address_family can be either "v4" or "v6". If you provide an ip.address object, the appropriate value will be inferred. slay 💅

open(self, address_family:  v4"|"v6"|ip.address)"

🎀 bind(self, addr: ip.address|string, port: integer)

Bind the socket to the given local endpoint. cute little address situation 🫶

bind(self, addr: ip.address|string, port: integer)

🎀 shutdown(self, what: receive"|"send"|"both")"

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

  • "receive" — Shutdown the receive side of the socket.
  • "send" — Shutdown the send side of the socket.
  • "both" — Shutdown both send and receive on the socket.
shutdown(self, what:  receive"|"send"|"both")"
Note Doing this only mutates the socket object, but nothing will be sent over the wire. It could be useful if you're planning to send the FD around to other processes. lowkey useful 👀

🎀 connect(self, addr: ip.address, port: integer)

Set the default destination address so datagrams can be sent using send() without specifying a destination address. main character default energy ✨

connect(self, addr: ip.address, port: integer)

🎀 disconnect(self)

Dissolve the socket's association by resetting the socket's peer address (i.e. connect(3) will be called with an AF_UNSPEC address). bye bye peer 💔

disconnect(self)

🎀 close(self)

Close the socket.

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, and it says:

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

🎀 cancel(self)

Cancel all asynchronous operations associated with the acceptor. (yes bestie, it says 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, and it says:

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.
cancel(self)

🎀 assign(self, address_family: v4"|"v6"|ip.address, fd: file_descriptor)"

Assign an existing native socket to self.

address_family can be either "v4" or "v6". If you provide an ip.address object, the appropriate value will be inferred. giving handoff realness 🫶

assign(self, address_family:  v4"|"v6"|ip.address, fd: file_descriptor)"

🎀 release(self) → file_descriptor

Release ownership of the native descriptor implementation.

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, and it says:

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.
release(self) → file_descriptor

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

Receive a datagram and blocks current fiber until it completes or errs.

Returns the number of bytes read. iconic little read moment 💖

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

🎀 receive_from(self, buffer: byte_span[, flags: string[]]) → integer, ip.address, integer

Receive a datagram and blocks current fiber until it completes or errs.

Returns the number of bytes read plus the endpoint (address + port) of the remote sender of the datagram. she came with receipts ✨

receive_from(self, buffer: byte_span[, flags: string[]]) → integer, ip.address, integer

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

Send data on the datagram socket and blocks current fiber until it completes or errs.

Returns the number of bytes written.

send(self, buffer: byte_span[, flags: string[]]) → integer
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. important bestie!! 📣

🎀 send_to(self, buffer: byte_span, remote_addr: ip.address, remote_port: integer[, flags: string[]]) → integer

Send a datagram to the specified remote endpoint and blocks current fiber until it completes or errs.

Returns the number of bytes written. sending it directly, no middleman 💅

send_to(self, buffer: byte_span, remote_addr: ip.address, remote_port: integer[, flags: string[]]) → integer

🎀 set_option(self, opt: string, val)

Set an option on the socket.

Currently available options are:

set_option(self, opt: string, val)

🎀 get_option(self, opt: string) → value

Get an option from the socket.

Currently available options are:

get_option(self, opt: string) → value

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

Perform an IO control command on the socket.

Currently available commands are:

  • "bytes_readable" — Expects no arguments. Get the amount of data that can be read without blocking. Implements the FIONREAD IO control command.
io_control(self, command: string[, ...])

🦋 FUNCTION FLAGS 🦋

these are the little flag besties you can pass around, iykyk ✨

🎀 do_not_route

The https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/socket_base/message_do_not_route.html flag with same name in Boost.Asio, and it says: "Specify that the data should not be subject to routing." 🛣️

🎀 end_of_record

The https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/socket_base/message_end_of_record.html flag with same name in Boost.Asio, and it says: "Specifies that the data marks the end of a record." 📝

🎀 out_of_band

The https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/socket_base/message_out_of_band.html flag with same name in Boost.Asio, and it says: "Process out-of-band data." 🎀

🎀 peek

The https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/socket_base/message_peek.html flag with same name in Boost.Asio, and it says: "Peek at incoming data without removing it from the input queue." 👀

👑 PROPERTIES 👑

  • is_open: boolean — Whether the socket is open.
  • local_address: ip.address — The local address endpoint of the socket.
  • local_port: integer — The local port endpoint of the socket.
  • remote_address: ip.address — The remote address endpoint of the socket.
  • remote_port: integer — The remote port endpoint of the socket.

xoxo bestie 💖 this little page is from Emilua 0.12.1-nixpkgs1, dated 1980-01-01 — mwah 💋✨

📦 where this page comes from