ark::comms::Socket

Defined in header “ark/comms/socket.hh”.

A wrapper around socket routines this is a low level wrapper that turns libsock routines into something more modern. The semantics of these APIs are about the same as their POSIX equivalents.

Methods

Socket(SocketType type, SocketFamily family)
Constructor. Creates a socket of the specific type.
Socket(native_handle_type fd)
A private constructor to allow you to initialize a socket against an existing descriptor. Note that if called, this socket now maintains ownership over the given descriptor.
Socket()
Disable copies. Otherwise we’re not sure who owns the descriptor for cleanup.
Socket & operator=()
~Socket()
Destructor. Cleans up the open socket handle.
void close()
Manually closes this socket handle. This is called automatically by the destructor. No more operations can be done on this socket after this is called.
native_handle_type native_handle()
Returns the underlying native handle for this object.
bool connect(const NetworkAddress & address)
Connects the socket to the given network address. If this socket is in non-blocking mode, this returns immediately. Otherwise, it blocks until a connection is established.

Returns true if a connection is made, or false otherwise.
bool connect(const std::string & path)
Connects the socket to the given local domain socket name. If this socket is in non-blocking mode, this returns immediately. Otherwise, it blocks until a connection is established.

Returns true if a connection is made, or false otherwise.
bool check_connection_status()
For non-blocking connections, this will check to determine if the connection is successful or not. This will return true if successful, false if its in progress, or throw an exception if there was an error.
void set_bind_device(const std::string & interface_name)
Sets the local interface name to bind to for bind() using SO_BINDTODEVICE socket option. Use before calling Socket::bind().

This follows POSIX conventions if you give an empty (zero) port, the socket will bind to a random free port.
void bind(const NetworkAddress & address)
Binds the socket to the given network address. This can fail if the socket is already bound.

This follows POSIX conventions if you give an empty (zero) port, the socket will bind to a random free port.
void bind(const std::string & path)
Binds the socket to the given path. This can fail if the socket is already bound.
void join_multicast_group(const NetworkAddress & multicast_address, const NetworkAddress & interface_address)
Joins the given multicast group on the given local interface IP, requesting membership. If given an empty interface IP, allows binding to any interface. Only valid for UDP sockets.
void listen(size_t backlog)
Instructs a previously bound socket that it should listen for incoming connections. The backlog is the number of connections that can be waiting for you to call accept() before it starts rejecting.
std::shared_ptr< Socket > accept()
If bound, and if there is a connection waiting on the backlog, this will accept the connection and return a reference to it.

This may not return a valid socket handle if we are non-blocking and nothing is waiting.
NetworkAddress address()
If bound, this will return the address that we are currently bound to. This can be used when binding to port zero, to determine which port you bound to.
NetworkAddress peer()
If there is a connection on this socket, returns the address of the other side of the connection.
void set_nonblocking(bool value)
Sets if this socket is non-blocking or not.
void set_reuse_address(bool value)
Sets if this socket can reuse its address or not.
void set_nodelay(bool value)
Enables TCP_NODELAY (disables Nagle’s algorithm). Only valid for TCP sockets. This will decrease latency by writing data as soon as it’s available. Typically decreases throughput.

This is often needed for some embedded boards that want to treat TCP as if it was packet-based.
void set_kernel_timestamping(bool value)
Enables socket timestamping. If this is enabled, then you can use the read_from overload that provides a timestamp, and that timestamp will contain the time that the packet was received by the kernel.
void set_receive_buffer_size(int32_t size)
Sets the kernel receive buffer size. Note that you need to ensure the base kernel is configured to allow this to be set.
void set_transmit_buffer_size(int32_t size)
Sets the kernel transmit buffer size. Note that you need to ensure the base kernel is configured to allow this to be set.
size_t get_receive_buffer_size()
Returns the current receive buffer size.
size_t get_transmit_buffer_size()
Returns the current transmit buffer size.
size_t write(const std::string_view & data, SocketWriteFlags flags)
Writes the given string of bytes over the socket. Returns the number of bytes actually written.
void write_checked(const std::string_view & data, SocketWriteFlags flags)
Writes the given string of bytes over the socket. Throws if all of the bytes were not written.
size_t write(const void * array, size_t array_size, SocketWriteFlags flags)
Writes the given number of bytes, from the specified array, over the socket. Returns the number of bytes actually written.
void write_checked(const void * array, size_t array_size, SocketWriteFlags flags)
Writes the given number of bytes, from the specified array, over the socket. Throws if all of the bytes were not written.
size_t write_to(const NetworkAddress & address, const void * array, size_t array_size)
Writes the given number of bytes, from the specified array, over the socket. Directs the message to the given network address. Returns the number of bytes actually written.
void write_to_checked(const NetworkAddress & address, const void * array, size_t array_size)
Writes the given number of bytes, from the specified array, over the socket. Directs the message to the given network address.

Throws if the number of bytes requested is not written.
std::optional< std::string > read(size_t maximum_length)
Reads a block of data from the socket and returns it as a string. This will read up-to the number of bytes specified, and return them in a newly-allocated string.

This does not guarantee you read all of the bytes you ask for (or, indeed, any bytes), just that it won’t read more then the bytes asked for.
std::optional< size_t > read(void * array, size_t maximum_length)
Reads a block of data from the socket and returns it in the given array. Reads no more then array_size bytes. Returns the number of bytes read (if any).
std::optional< size_t > read_from(NetworkAddress & address, void * array, size_t maximum_length)
Reads a block of data from the socket and returns it in the given array. Reads no more then array_size bytes. The address that the data was received from will be copied into the address parameter.

Returns the number of bytes read (if any).
std::optional< size_t > read_from(NetworkAddress & address, std::chrono::system_clock::time_point & receive_time, void * array, size_t maximum_length)
Reads a block of data from the socket and returns it in the given array. Reads no more then array_size bytes.

The address that the data was received from will be copied into the address parameter. The timestamp of when the data was received will be returned into the receive_time parameter. This value will be the best possible timestamp based on system configuration. Note that timestamps can only be returned (this will throw otherwise) if set_kernel_timestamping is enabled. Returns the number of bytes read (if any).
bool wait_for(core::PollEventFlags event, std::chrono::nanoseconds duration)
Waits for this socket to be ready for the specific event (either a read or a write). Returns true if the socket is ready for the event when this routine returns, or false otherwise.
bool valid()
Indiciates if this socket is “good” (open, with a valid descriptor, and not closed).
operator bool()
A convenience wrapper for valid().
bool operator==(const Socket & rhs)
An operator to test sockets for equality.
bool operator<(const Socket & rhs)
An operator to test sockets for less than, for maps.