iodine 0.4.19 → 0.5.0

data/ext/iodine/sock.h

@@ -7,58 +7,63 @@ License: MIT
 Feel free to copy, use and enjoy according to the license provided.
 */
 #define LIB_SOCK_VERSION_MAJOR 0
-#define LIB_SOCK_VERSION_MINOR 3
-#define LIB_SOCK_VERSION_PATCH 2
+#define LIB_SOCK_VERSION_MINOR 4
+#define LIB_SOCK_VERSION_PATCH 0
 
+#ifndef LIB_SOCK_MAX_CAPACITY
+/** The maximum `fd` value `sock.h` should support. */
+#define LIB_SOCK_MAX_CAPACITY 131072
+#endif
 /** \file
-The `sock.h` is a non-blocking socket helper library, using a user level buffer,
-non-blocking sockets and some helper functions.
-
-This library is great when using it alongside `evio.h`.
-
-The library is designed to be thread safe, but not fork safe - mostly since
-sockets, except listenning sockets, shouldn't be shared among processes.
-
-Socket connections accepted or created using this library will use the
-TCP_NODELAY option by default.
-
-Non TCP/IP stream sockets and file descriptors (i.e., unix sockets) can be
-safely used with this library. However, file descriptors that can't use the
-`read` or `write` system calls MUST set correct Read / Write hooks or they will
-fail.
-*/
+ * The `sock.h` is a non-blocking socket helper library, using a user level
+ * buffer, non-blocking sockets and some helper functions.
+ *
+ * This library is great when using it alongside `evio.h`.
+ *
+ * The library is designed to be thread safe, but not fork safe - mostly since
+ * sockets, except listenning sockets, shouldn't be shared among processes.
+ *
+ * Socket connections accepted or created using this library will use the
+ * TCP_NODELAY option by default.
+ *
+ * Non TCP/IP stream sockets and file descriptors (i.e., unix sockets) can be
+ * safely used with this library. However, file descriptors that can't use the
+ * `read` or `write` system calls MUST set correct Read / Write hooks or they
+ * will fail.
+ */
 
 #include <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
+#include <string.h>
 #include <sys/types.h>
 #include <unistd.h>
 
-#ifndef UNUSED_FUNC
-#define UNUSED_FUNC __attribute__((unused))
+// clang-format off
+#if !defined(__BIG_ENDIAN__) && !defined(__LITTLE_ENDIAN__)
+#   if defined(__has_include)
+#     if __has_include(<endian.h>)
+#      include <endian.h>
+#     elif __has_include(<sys/endian.h>)
+#      include <sys/endian.h>
+#     endif
+#   endif
+#   if !defined(__BIG_ENDIAN__) && !defined(__LITTLE_ENDIAN__) && \
+                __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
+#      define __BIG_ENDIAN__
+#   endif
 #endif
+// clang-format on
 
-/* *****************************************************************************
-User land buffer settings for every packet's pre-alocated memory size (17Kb)
-
-This information is also useful when implementing read / write hooks.
-*/
-#ifndef BUFFER_PACKET_SIZE
-#define BUFFER_PACKET_SIZE                                                     \
-  (1024 * 16) /* Use 32 Kb. With sendfile, 16 Kb appears to work better. */
-#endif
-#ifndef BUFFER_FILE_READ_SIZE
-#define BUFFER_FILE_READ_SIZE 4096UL
-#endif
-#ifndef BUFFER_PACKET_POOL
-#define BUFFER_PACKET_POOL 1024
+#ifndef UNUSED_FUNC
+#define UNUSED_FUNC __attribute__((unused))
 #endif
 
 /* *****************************************************************************
 A simple, predictable UUID for file-descriptors, for collision prevention
 */
 #ifndef sock_uuid2fd
-#define sock_uuid2fd(uuid) ((intptr_t)((uintptr_t)uuid >> 8))
+#define sock_uuid2fd(uuid) ((int)((uintptr_t)uuid >> 8))
 #endif
 
 /* *****************************************************************************
@@ -69,15 +74,18 @@ extern "C" {
 #endif
 
 /* *****************************************************************************
-Process wide and helper sock_API.
+Process wide and helper sock API.
 */
 
-/**
-Sets a socket to non blocking state.
+/** MUST be called after forking a process. */
+void sock_on_fork(void);
 
-This function is called automatically for the new socket, when using
-`sock_accept` or `sock_connect`.
-*/
+/**
+ * Sets a socket to non blocking state.
+ *
+ * This function is called automatically for the new socket, when using
+ * `sock_accept` or `sock_connect`.
+ */
 int sock_set_non_block(int fd);
 
 /**
@@ -90,103 +98,119 @@ extended to the allowed "hard" limit.
 ssize_t sock_max_capacity(void);
 
 /* *****************************************************************************
-The main sock_API.
+The main sock API.
 */
 
 /**
-Opens a listening non-blocking socket. Return's the socket's UUID.
-
-Returns -1 on error. Returns a valid socket (non-random) UUID.
-
-UUIDs with values less then -1 are valid values, depending on the system's
-byte-ordering.
-
-Socket UUIDs are predictable and shouldn't be used outside the local system.
-They protect against connection mixups on concurrent systems (i.e. when saving
-client data for "broadcasting" or when an old client task is preparing a
-response in the background while a disconnection and a new connection occur on
-the same `fd`).
-*/
+ * Opens a listening non-blocking socket. Return's the socket's UUID.
+ *
+ * If `port` is provided (`address` can be NULL), a TCP/IP socket will be
+ * opened. Otherwise, `address` is required and a Unix Socket will be used
+ * (remember Unix Sockets have name length restrictions).
+ *
+ * Returns -1 on error. Returns a valid socket (non-random) UUID.
+ *
+ * UUIDs with values less then -1 are valid values, depending on the system's
+ * byte-ordering.
+ *
+ * Socket UUIDs are predictable and shouldn't be used outside the local system.
+ * They protect against connection mixups on concurrent systems (i.e. when
+ * saving client data for "broadcasting" or when an old client task is preparing
+ * a response in the background while a disconnection and a new connection occur
+ * on the same `fd`).
+ */
 intptr_t sock_listen(const char *address, const char *port);
 
 /**
-`sock_accept` accepts a new socket connection from the listening socket
-`server_fd`, allowing the use of `sock_` functions with this new file
-descriptor.
-
-When using `libreact`, remember to call `int reactor_add(intptr_t uuid);` to
-listen for events.
-
-Returns -1 on error. Returns a valid socket (non-random) UUID.
-
-Socket UUIDs are predictable and shouldn't be used outside the local system.
-They protect against connection mixups on concurrent systems (i.e. when saving
-client data for "broadcasting" or when an old client task is preparing a
-response in the background while a disconnection and a new connection occur on
-the same `fd`).
+* `sock_accept` accepts a new socket connection from the listening socket
+* `server_fd`, allowing the use of `sock_` functions with this new file
+* descriptor.
+
+* When using `evio`, remember to call `int evio_add(intptr_t uuid);` to
+* listen for events.
+*
+* Returns -1 on error. Returns a valid socket (non-random) UUID.
+*
+* Socket UUIDs are predictable and shouldn't be used outside the local system.
+* They protect against connection mixups on concurrent systems (i.e. when saving
+* client data for "broadcasting" or when an old client task is preparing a
+* response in the background while a disconnection and a new connection occur on
+* the same `fd`).
 */
 intptr_t sock_accept(intptr_t srv_uuid);
 
 /**
-`sock_connect` is similar to `sock_accept` but should be used to initiate a
-client connection to the address requested.
-
-Returns -1 on error. Returns a valid socket (non-random) UUID.
-
-Socket UUIDs are predictable and shouldn't be used outside the local system.
-They protect against connection mixups on concurrent systems (i.e. when saving
-client data for "broadcasting" or when an old client task is preparing a
-response in the background while a disconnection and a new connection occur on
-the same `fd`).
-
-When using `evio`, remember to call `int evio_add(sock_fd2uuid(uuid),
-(void*)uuid);` to listen for events.
-
-NOTICE:
-
-This function is non-blocking, meaning that the connection probably wasn't
-established by the time the function returns (this prevents the function from
-hanging while waiting for a network timeout).
-
-Use select, poll, `evio` or other solutions to review the connection state
-before attempting to write to the socket.
-*/
+ * `sock_connect` is similar to `sock_accept` but should be used to initiate a
+ * client connection to the address requested.
+ *
+ * If `port` is provided (`address` can be NULL), a TCP/IP socket will be
+ * opened. Otherwise, `address` is required and a Unix Socket will be used
+ * (remember Unix Sockets have name length restrictions).
+ *
+ * Returns -1 on error. Returns a valid socket (non-random) UUID.
+ *
+ * Socket UUIDs are predictable and shouldn't be used outside the local system.
+ * They protect against connection mixups on concurrent systems (i.e. when
+ * saving client data for "broadcasting" or when an old client task is preparing
+ * a response in the background while a disconnection and a new connection occur
+ * on the same `fd`).
+ *
+ * When using `evio`, remember to call `int evio_add(sock_fd2uuid(uuid),
+ * (void*)uuid);` to listen for events.
+ *
+ * NOTICE:
+ *
+ * This function is non-blocking, meaning that the connection probably wasn't
+ * established by the time the function returns (this prevents the function from
+ * hanging while waiting for a network timeout).
+ *
+ * Use select, poll, `evio` or other solutions to review the connection state
+ * before attempting to write to the socket.
+ */
 intptr_t sock_connect(char *address, char *port);
 
 /**
-`sock_open` takes an existing file descriptor `fd` and initializes it's status
-as open and available for `sock_API` calls, returning a valid UUID.
-
-This will reinitialize the data (user buffer etc') for the file descriptor
-provided, calling the `sock_on_close` callback if the `fd` was previously
-marked as used.
-
-When using `evio`, remember to call `int evio_add(sock_fd2uuid(uuid),
-(void*)uuid);` to listen for events.
-
-Returns -1 on error. Returns a valid socket (non-random) UUID.
-
-Socket UUIDs are predictable and shouldn't be used outside the local system.
-They protect against connection mixups on concurrent systems (i.e. when saving
-client data for "broadcasting" or when an old client task is preparing a
-response in the background while a disconnection and a new connection occur on
-the same `fd`).
+* `sock_open` takes an existing file descriptor `fd` and initializes it's status
+* as open and available for `sock_*` API calls, returning a valid UUID.
+*
+* This will reinitialize the data (user buffer etc') for the file descriptor
+* provided, calling the `sock_on_close` callback if the `fd` was previously
+* marked as used.
+
+* When using `evio`, remember to call `int evio_add(sock_fd2uuid(uuid),
+* (void*)uuid);` to listen for events.
+*
+* Returns -1 on error. Returns a valid socket (non-random) UUID.
+*
+* Socket UUIDs are predictable and shouldn't be used outside the local system.
+* They protect against connection mixups on concurrent systems (i.e. when saving
+* client data for "broadcasting" or when an old client task is preparing a
+* response in the background while a disconnection and a new connection occur on
+* the same `fd`).
 */
 intptr_t sock_open(int fd);
 
 /**
-Returns 1 if the uuid refers to a valid and open, socket.
+ * Returns 1 if the uuid refers to a valid and open, socket.
+ *
+ * Returns 0 if not.
+ */
+int sock_isvalid(intptr_t uuid);
+
+/**
+Returns 1 if the uuid is invalid or the socket is flagged to be closed.
 
-Returns 0 if not.
+Returns 0 if the socket is valid, open and isn't flagged to be closed.
 */
-int sock_isvalid(intptr_t uuid);
+int sock_isclosed(intptr_t uuid);
 
 /** The return type for the `sock_peer_addr` function. */
 typedef struct {
   uint32_t addrlen;
   struct sockaddr *addr;
 } sock_peer_addr_s;
-/** Returns the information available about the socket's peer address.
+/**
+ * Returns the information available about the socket's peer address.
  *
  * If no information is available, the struct will be initialized with zero
  * (`addr == NULL`).
@@ -196,66 +220,67 @@ typedef struct {
 sock_peer_addr_s sock_peer_addr(intptr_t uuid);
 
 /**
-`sock_fd2uuid` takes an existing file decriptor `fd` and returns it's active
-`uuid`.
-
-If the file descriptor is marked as closed (wasn't opened / registered with
-`libsock`) the function returns -1;
-
-If the file descriptor was closed remotely (or not using `libsock`), a false
-positive will be possible. This is not an issue, since the use of an invalid fd
-will result in the registry being updated and the fd being closed.
-
-Returns -1 on error. Returns a valid socket (non-random) UUID.
+* `sock_fd2uuid` takes an existing file decriptor `fd` and returns it's active
+* `uuid`.
+
+* If the file descriptor is marked as closed (wasn't opened / registered with
+* `libsock`) the function returns -1;
+*
+* If the file descriptor was closed remotely (or not using `libsock`), a false
+* positive will be possible. This is not an issue, since the use of an invalid
+fd
+* will result in the registry being updated and the fd being closed.
+*
+* Returns -1 on error. Returns a valid socket (non-random) UUID.
 */
 intptr_t sock_fd2uuid(int fd);
 
 /**
-OVERRIDABLE:
-
-"Touches" a socket connection.
-
-This is a place holder for an optional callback for systems that apply timeout
-reviews.
-
-`sock` supplies a default implementation (that does nothing) is cases where a
-callback wasn't defined.
-*/
+ * OVERRIDABLE:
+ *
+ * "Touches" a socket connection.
+ *
+ * This is a place holder for an optional callback for systems that apply
+ * timeout reviews.
+ *
+ * `sock` supplies a default implementation (that does nothing) is cases where a
+ * callback wasn't defined.
+ */
 void sock_touch(intptr_t uuid);
 
 /**
-OVERRIDABLE:.
-
-This is a place holder for an optional callback for when the socket is closed
-locally.
-
-Notice that calling `sock_close()` won't close the socket before all the data in
-the buffer is sent. This function will be called only one the connection is
-actually closed.
-
-`sock` supplies a default implementation (that does nothing) is cases where a
-callback wasn't defined.
-*/
+ * OVERRIDABLE:.
+ *
+ * This is a place holder for an optional callback for when the socket is closed
+ * locally.
+ *
+ * Notice that calling `sock_close()` won't close the socket before all the data
+ * in the buffer is sent. This function will be called only one the connection
+ * is actually closed.
+ *
+ * `sock` supplies a default implementation (that does nothing) is cases where a
+ * callback wasn't defined.
+ */
 void sock_on_close(intptr_t uuid);
 
 /**
-`sock_read` attempts to read up to count bytes from the socket into the buffer
-starting at buf.
-
-`sock_read`'s return values are wildly different then the native return values
-and they aim at making far simpler sense.
-
-`sock_read` returns the number of bytes read (0 is a valid return value which
-simply means that no bytes were read from the buffer).
-
-On a connection error (NOT EAGAIN or EWOULDBLOCK), signal interrupt, or when the
-connection was closed, `sock_read` returns -1.
-
-The value 0 is the valid value indicating no data was read.
-
-Data might be available in the kernel's buffer while it is not available to be
-read using `sock_read` (i.e., when using a transport layer, such as TLS).
-*/
+ * `sock_read` attempts to read up to count bytes from the socket into the
+ * buffer starting at buf.
+ *
+ * `sock_read`'s return values are wildly different then the native return
+ * values and they aim at making far simpler sense.
+ *
+ * `sock_read` returns the number of bytes read (0 is a valid return value which
+ * simply means that no bytes were read from the buffer).
+ *
+ * On a connection error (NOT EAGAIN or EWOULDBLOCK), signal interrupt, or when
+ * the connection was closed, `sock_read` returns -1.
+ *
+ * The value 0 is the valid value indicating no data was read.
+ *
+ * Data might be available in the kernel's buffer while it is not available to
+ * be read using `sock_read` (i.e., when using a transport layer, such as TLS).
+ */
 ssize_t sock_read(intptr_t uuid, void *buf, size_t count);
 
 typedef struct {
@@ -268,27 +293,31 @@ typedef struct {
     const intptr_t data_fd;
   };
   union {
-    /** This deallocation callback will be called when the packet is finished
+    /**
+     * This deallocation callback will be called when the packet is finished
      * with the buffer if the `move` flags is set.
+     *
      * If no deallocation callback is `free` will be used.
+     *
+     * Note: `sock` library functions MUST NEVER be called by a callback, or a
+     * deadlock might occur.
      */
     void (*dealloc)(void *buffer);
-    /** This is an alternative deallocation callback accessor (same memory space
+    /**
+     * This is an alternative deallocation callback accessor (same memory space
      * as `dealloc`) for conveniently setting the file `close` callback.
+     *
+     * Note: `sock` library functions MUST NEVER be called by a callback, or a
+     * deadlock might occur.
      */
     void (*close)(intptr_t fd);
   };
   /** The length (size) of the buffer, or the amount of data to be sent from the
    * file descriptor.
    */
-  size_t length;
+  uintptr_t length;
   /** Starting point offset from the buffer or file descriptor's beginning. */
-  off_t offset;
-  /** When sending data from the memory, using `move` will prevent copy and
-   * memory allocations, moving the memory ownership to the `sock_write2`
-   * function.
-   */
-  unsigned move : 1;
+  intptr_t offset;
   /** The packet will be sent as soon as possible. */
   unsigned urgent : 1;
   /**
@@ -311,189 +340,208 @@ typedef struct {
 } sock_write_info_s;
 
 void SOCK_DEALLOC_NOOP(void *arg);
-#define SOCK_DEALLOC_NOOP SOCK_DEALLOC_NOOP
+#define SOCK_CLOSE_NOOP ((void (*)(intptr_t))SOCK_DEALLOC_NOOP)
 
 /**
-`sock_write2_fn` is the actual function behind the macro `sock_write2`.
-*/
+ * `sock_write2_fn` is the actual function behind the macro `sock_write2`.
+ */
 ssize_t sock_write2_fn(sock_write_info_s options);
 
 /**
-`sock_write2` is similar to `sock_write`, except special properties can be set.
-
-On error, -1 will be returned. Otherwise returns 0. All the bytes are
-transferred to the socket's user level buffer.
-*/
+ * `sock_write2` is similar to `sock_write`, except special properties can be
+ * set.
+ *
+ * On error, -1 will be returned. Otherwise returns 0. All the bytes are
+ * transferred to the socket's user level buffer.
+ */
 #define sock_write2(...) sock_write2_fn((sock_write_info_s){__VA_ARGS__})
 /**
-`sock_write` writes up to count bytes from the buffer pointed `buf` to the
-buffer associated with the socket `sockfd`.
-
-The data isn't necessarily written to the socket and multiple calls to
-`sock_flush` might be required before all the data is actually sent.
-
-On error, -1 will be returned. Otherwise returns 0. All the bytes are
-transferred to the socket's user level buffer.
-
-**Note** this is actually a specific case of `sock_write2` and this macro
-actually calls `sock_write2`.
-*/
-#define sock_write(sock_uuid, buf, count)                                      \
-  sock_write2(.uuid = (sock_uuid), .buffer = (buf), .length = (count))
+ * `sock_write` copies `legnth` data from the buffer and schedules the data to
+ * be sent over the socket.
+ *
+ * The data isn't necessarily written to the socket and multiple calls to
+ * `sock_flush` might be required before all the data is actually sent.
+ *
+ * On error, -1 will be returned. Otherwise returns 0. All the bytes are
+ * transferred to the socket's user level buffer.
+ *
+ * Returns the same values as `sock_write2`.
+ */
+// ssize_t sock_write(uintptr_t uuid, void *buffer, size_t legnth);
+UNUSED_FUNC static inline ssize_t
+sock_write(const intptr_t uuid, const void *buffer, const size_t length) {
+  if (!length || !buffer)
+    return 0;
+  void *cpy = malloc(length);
+  if (!cpy)
+    return -1;
+  memcpy(cpy, buffer, length);
+  return sock_write2(.uuid = uuid, .buffer = cpy, .length = length);
+}
 
 /**
-Sends data from a file as if it were a single atomic packet (sends up to
-length bytes or until EOF is reached).
-
-Once the file was sent, the `source_fd` will be closed using `close`.
-
-The file will be buffered to the socket chunk by chunk, so that memory
-consumption is capped. The system's `sendfile` might be used if conditions
-permit.
-
-`offset` dictates the starting point for te data to be sent and length sets
-the maximum amount of data to be sent.
-
-Returns -1 and closes the file on error. Returns 0 on success.
-*/
+ * Sends data from a file as if it were a single atomic packet (sends up to
+ * length bytes or until EOF is reached).
+ *
+ * Once the file was sent, the `source_fd` will be closed using `close`.
+ *
+ * The file will be buffered to the socket chunk by chunk, so that memory
+ * consumption is capped. The system's `sendfile` might be used if conditions
+ * permit.
+ *
+ * `offset` dictates the starting point for te data to be sent and length sets
+ * the maximum amount of data to be sent.
+ *
+ * Returns -1 and closes the file on error. Returns 0 on success.
+ */
 UNUSED_FUNC static inline ssize_t
 sock_sendfile(intptr_t uuid, intptr_t source_fd, off_t offset, size_t length) {
   return sock_write2(.uuid = uuid, .buffer = (void *)(source_fd),
-                     .length = length, .is_fd = 1, .offset = offset, .move = 1);
+                     .length = length, .is_fd = 1, .offset = offset);
 }
 
 /**
-`sock_flush` writes the data in the internal buffer to the underlying file
-descriptor and closes the underlying fd once it's marked for closure (and all
-the data was sent).
+ * `sock_close` marks the connection for disconnection once all the data was
+ * sent. The actual disconnection will be managed by the `sock_flush` function.
+ *
+ * `sock_flash` will automatically be called.
+ */
+void sock_close(intptr_t uuid);
 
-Return value: 0 will be returned on success and -1 will be returned on an error
-or when the connection is closed.
-*/
-ssize_t sock_flush(intptr_t uuid);
-/**
-`sock_flush_strong` performs the same action as `sock_flush` but returns only
-after all the data was sent. This is a "busy" wait, polling isn't performed.
-*/
-void sock_flush_strong(intptr_t uuid);
 /**
-Calls `sock_flush` for each file descriptor that's buffer isn't empty.
-*/
-void sock_flush_all(void);
-/**
-`sock_close` marks the connection for disconnection once all the data was sent.
-The actual disconnection will be managed by the `sock_flush` function.
+ * `sock_force_close` closes the connection immediately, without adhering to any
+ * protocol restrictions and without sending any remaining data in the
+ * connection buffer.
+ */
+void sock_force_close(intptr_t uuid);
 
-`sock_flash` will automatically be called.
-*/
-void sock_close(intptr_t uuid);
 /**
-`sock_force_close` closes the connection immediately, without adhering to any
-protocol restrictions and without sending any remaining data in the connection
-buffer.
-*/
-void sock_force_close(intptr_t uuid);
+ * `sock_hijack` is the reverse of the `sock_open` function, removing the
+ * connection from the `sock` library and clearing it's data without closing it
+ * (`sock_on_close` will NOT be called).
+ *
+ * Returns the original `fd` for the socket. On error returns -1.
+ */
+int sock_hijack(intptr_t uuid);
 
 /* *****************************************************************************
 Direct user level buffer API.
-
-The following API allows data to be written directly to the packet, minimizing
-memory copy operations.
 */
 
 /**
-The buffer of a user-land sock-packet.
-
-Remember to set the correct `len` value, so the full amount of the data is sent.
-
-See `sock_buffer_checkout`, `sock_buffer_send` and `sock_buffer_free` for more
-information.
-*/
-typedef struct sock_buffer_s {
-  size_t len;
-  uint8_t buf[BUFFER_PACKET_SIZE];
-} sock_buffer_s;
+ * `sock_flush` writes the data in the internal buffer to the underlying file
+ * descriptor and closes the underlying fd once it's marked for closure (and all
+ * the data was sent).
+ *
+ * Return values: 1 will be returned if `sock_flush` should be called again. 0
+ * will be returned if the socket was fully flushed. -1 will be returned on an
+ * error or when the connection is closed.
+ */
+ssize_t sock_flush(intptr_t uuid);
 
 /**
-Checks out a `sock_buffer_s` from the buffer pool.
-
-This function will hang until a buffer becomes available, so never check out
-more then a single buffer at a time and remember to free or send the buffer
-using the `sock_buffer_*` functions.
-
-Every checked out buffer packet comes with an attached buffer of
-BUFFER_PACKET_SIZE bytes. This buffer is accessible using the `->buf`
-pointer.
+ * `sock_flush_strong` performs the same action as `sock_flush` but returns only
+ * after all the data was sent. This is a "busy" wait, polling isn't performed.
+ */
+void sock_flush_strong(intptr_t uuid);
 
-This attached buffer's memory is automatically manages as long as the
-`sock_buffer_send` or `sock_buffer_free` functions are called.
-*/
-sock_buffer_s *sock_buffer_checkout(void);
 /**
-Attaches a packet to a socket's output buffer and calls `sock_flush` for the
-socket.
+ * Calls `sock_flush` for each file descriptor that's buffer isn't empty.
+ */
+void sock_flush_all(void);
 
-Returns -1 on error. Returns 0 on success. The `buffer` memory is always
-automatically managed.
-*/
-ssize_t sock_buffer_send(intptr_t uuid, sock_buffer_s *buffer);
+/**
+ * Returns the number of `sock_write` calls that are waiting in the socket's
+ * queue and haven't been processed.
+ *
+ * This method will be deprecated in the 0.7.0 release. Use `sock_pending`
+ * instead.
+ */
+int __attribute__((deprecated("use sock_pending instead")))
+sock_has_pending(intptr_t uuid);
 
 /**
-Returns TRUE (non 0) if there is data waiting to be written to the socket in the
-user-land buffer.
-*/
-int sock_has_pending(intptr_t uuid);
+ * Returns the number of `sock_write` calls that are waiting in the socket's
+ * queue and haven't been processed.
+ */
+size_t sock_pending(intptr_t uuid);
 
 /**
-Use `sock_buffer_free` to free unused buffers that were checked-out using
-`sock_buffer_checkout`.
-*/
-void sock_buffer_free(sock_buffer_s *buffer);
+ * This weak function can be overwritten when using the `defer` library.
+ * However, the function MUST call {sock_flush} at some point.
+ */
+void sock_flush_defer(void *arg, void *ignored);
 
 /* *****************************************************************************
 TLC - Transport Layer Callback.
-
-Experimental
 */
 
 /**
-The following struct is used for setting a the read/write hooks that will
-replace the default system calls to `recv` and `write`. */
+ * The following struct is used for setting a the read/write hooks that will
+ * replace the default system calls to `recv` and `write`.
+ *
+ * Note: `sock` library functions MUST NEVER be called by any callback, or a
+ * deadlock might occur.
+ */
 typedef struct sock_rw_hook_s {
-  /** Implement reading from a file descriptor. Should behave like the file
-   * system `read` call, including the setup or errno to EAGAIN / EWOULDBLOCK.*/
-  ssize_t (*read)(intptr_t uuid, void *buf, size_t count);
-  /** Implement writing to a file descriptor. Should behave like the file system
-   * `write` call.*/
-  ssize_t (*write)(intptr_t uuid, const void *buf, size_t count);
-  /** When implemented, this function will be called to flush any data remaining
+  /**
+   * Implement reading from a file descriptor. Should behave like the file
+   * system `read` call, including the setup or errno to EAGAIN / EWOULDBLOCK.
+   *
+   * Note: `sock` library functions MUST NEVER be called by any callback, or a
+   * deadlock might occur.
+   */
+  ssize_t (*read)(intptr_t uuid, void *udata, void *buf, size_t count);
+  /**
+   * Implement writing to a file descriptor. Should behave like the file system
+   * `write` call.
+   *
+   * Note: `sock` library functions MUST NEVER be called by any callback, or a
+   * deadlock might occur.
+   */
+  ssize_t (*write)(intptr_t uuid, void *udata, const void *buf, size_t count);
+  /**
+   * When implemented, this function will be called to flush any data remaining
    * in the internal buffer.
+   *
    * The function should return the number of bytes remaining in the internal
    * buffer (0 is a valid response) on -1 (on error).
+   *
    * It is important thet the `flush` function write to the underlying fd until
-   * the
-   * writing operation returns -1 with EWOULDBLOCK or all the data was written.
+   * the writing operation returns -1 with EWOULDBLOCK or all the data was
+   * written.
+   *
+   * Note: `sock` library functions MUST NEVER be called by any callback, or a
+   * deadlock might occur.
    */
-  ssize_t (*flush)(intptr_t fduuid);
-  /** The `on_close` callback is called when the socket is closed, allowing for
+  ssize_t (*flush)(intptr_t uuid, void *udata);
+  /**
+   * The `on_close` callback is called when the socket is closed, allowing for
    * dynamic sock_rw_hook_s memory management.
    *
    * The `on_close` callback should manage is own thread safety mechanism, if
-   * required. */
-  void (*on_close)(intptr_t fduuid, struct sock_rw_hook_s *rw_hook);
+   * required.
+   *
+   * Note: `sock` library functions MUST NEVER be called by any callback, or a
+   * deadlock might occur.
+   * */
+  void (*on_close)(intptr_t uuid, struct sock_rw_hook_s *rw_hook, void *udata);
 } sock_rw_hook_s;
 
 /* *****************************************************************************
 RW hooks implementation
 */
 
+/** Sets a socket hook state (a pointer to the struct). */
+int sock_rw_hook_set(intptr_t uuid, sock_rw_hook_s *rw_hooks, void *udata);
+
 /** Gets a socket hook state (a pointer to the struct). */
-struct sock_rw_hook_s *sock_rw_hook_get(intptr_t fduuid);
+struct sock_rw_hook_s *sock_rw_hook_get(intptr_t uuid);
 
-/** Sets a socket hook state (a pointer to the struct). */
-int sock_rw_hook_set(intptr_t fduuid, sock_rw_hook_s *rw_hooks);
+/** Returns the socket's udata associated with the read/write hook. */
+void *sock_rw_udata(intptr_t uuid);
 
-/** The default Read/Write hooks used for system Read/Write */
+/** The default Read/Write hooks used for system Read/Write (udata == NULL). */
 extern const sock_rw_hook_s SOCK_DEFAULT_HOOKS;
 
 /* *****************************************************************************