sock: extend API for asynchronous event management

sys/include/net/sock.h

@@ -103,6 +103,15 @@
 
 #include <stdint.h>
 
+#if defined(MODULE_SOCK_ASYNC) && !defined(DOXYGEN)
+#define SOCK_HAS_ASYNC      /**< allow sock_async to be defined as a provided
+                             *   feature of a stack */
+#endif
+
+#if defined(SOCK_HAS_ASYNC) && defined(RIOT_VERSION)
+#include "event.h"
+#endif
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -114,6 +123,7 @@ extern "C" {
  * @{
  */
 #define SOCK_HAS_IPV6       /**< activate IPv6 support */
+#define SOCK_HAS_ASYNC      /**< activate asynchronous event functionality */
 /** @} */
 #endif
 
@@ -152,6 +162,26 @@ extern "C" {
  */
 #define SOCK_NO_TIMEOUT     (UINT32_MAX)
 
+#if defined(SOCK_HAS_ASYNC) || defined(DOXYGEN)
+/**
+ * @brief   Event types for asynchronous event functionality
+ * @note    Only available with @ref SOCK_HAS_ASYNC defined.
+ * @anchor  net_sock_event_type
+ * @{
+ */
+#define SOCK_EVENT_RECV     (0x00000001)    /**< Receive event */
+/** @} */
+
+/**
+ * @brief   Sock event
+ */
+typedef struct {
+    event_t super;          /**< event_callback_t structure that gets extended */
+    void *sock;             /**< sock that emitted the event */
+    uint32_t type;          /**< [Event type](@ref net_sock_event_type) flags */
+} sock_event_t;
+#endif
+
 /**
  * @brief   Abstract IP end point and end point for a raw IP sock object
  */

sys/include/net/sock/ip.h

@@ -332,6 +332,26 @@ typedef struct sock_ip sock_ip_t;
 int sock_ip_create(sock_ip_t *sock, const sock_ip_ep_t *local,
                    const sock_ip_ep_t *remote, uint8_t proto, uint16_t flags);
 
+#if defined(SOCK_HAS_ASYNC) || defined(DOXYGEN)
+/**
+ * @brief   Set the event queue for asynchronous events for a raw IPv4/IPv6 sock
+ *          object
+ *
+ * @pre     `sock != NULL`
+ *
+ * @note    Only one event queue per sock can be set. Since
+ *          event_queue_t::waiter only allows for one thread to own the queue.
+ *          This also implies, that **only one thread can execute the
+ *          @p handler**!
+ *
+ * @param[in] sock      The sock to set the event queue for. May not be `NULL`.
+ * @param[in] queue     The queue to set. May be `NULL` to unset the queue.
+ * @param[in] handler   The event handler. May be `NULL` to unset.
+ */
+void sock_ip_set_event_queue(sock_ip_t *sock, event_queue_t *queue,
+                             event_handler_t handler);
+#endif
+
 /**
  * @brief   Closes a raw IPv4/IPv6 sock object
  *

sys/include/net/sock/tcp.h

@@ -387,6 +387,26 @@ int sock_tcp_listen(sock_tcp_queue_t *queue, const sock_tcp_ep_t *local,
                     sock_tcp_t *queue_array, unsigned queue_len,
                     uint16_t flags);
 
+#if defined(SOCK_HAS_ASYNC) || defined(DOXYGEN)
+/**
+ * @brief   Set the event queue for asynchronous events for a TCP sock
+ *          object
+ *
+ * @pre     `sock != NULL`
+ *
+ * @note    Only one event queue per sock can be set. Since
+ *          event_queue_t::waiter only allows for one thread to own the queue.
+ *          This also implies, that **only one thread can execute the
+ *          @p handler**!
+ *
+ * @param[in] sock      The sock to set the event queue for. May not be `NULL`.
+ * @param[in] queue     The queue to set. May be `NULL` to unset the queue.
+ * @param[in] handler   The event handler. May be `NULL` to unset.
+ */
+void sock_tcp_set_event_handler(sock_tcp_t *sock, event_queue_t *queue,
+                                event_handler_t handler);
+#endif
+
 /**
  * @brief   Disconnects a TCP connection
  *

sys/include/net/sock/udp.h

@@ -333,6 +333,25 @@ typedef struct sock_udp sock_udp_t;
 int sock_udp_create(sock_udp_t *sock, const sock_udp_ep_t *local,
                     const sock_udp_ep_t *remote, uint16_t flags);
 
+#if defined(SOCK_HAS_ASYNC) || defined(DOXYGEN)
+/**
+ * @brief   Set the event queue for asynchronous events for a UDP sock object
+ *
+ * @pre     `sock != NULL`
+ *
+ * @note    Only one event queue per sock can be set. Since
+ *          event_queue_t::waiter only allows for one thread to own the queue.
+ *          This also implies, that **only one thread can execute the
+ *          @p handler**!
+ *
+ * @param[in] sock      The sock to set the event queue for. May not be `NULL`.
+ * @param[in] queue     The queue to set. May be `NULL` to unset the queue.
+ * @param[in] handler   The event handler. May be `NULL` to unset.
+ */
+void sock_udp_set_event_queue(sock_udp_t *sock, event_queue_t *queue,
+                              event_handler_t handler);
+#endif
+
 /**
  * @brief   Closes a UDP sock object
  *