early draft for libgnunetpq event notification support

3 files changed, 214 insertions, 20 deletions

diff --git a/src/include/gnunet_common.h b/src/include/gnunet_common.h
index 1126deaf4..df1ccff26 100644
--- a/src/include/gnunet_common.h
+++ b/src/include/gnunet_common.h
@@ -435,11 +435,12 @@ enum GNUNET_ErrorType
  * @param date when was the message logged?
  * @param message what is the message
  */
-typedef void (*GNUNET_Logger) (void *cls,
-                               enum GNUNET_ErrorType kind,
-                               const char *component,
-                               const char *date,
-                               const char *message);
+typedef void
+(*GNUNET_Logger) (void *cls,
+                  enum GNUNET_ErrorType kind,
+                  const char *component,
+                  const char *date,
+                  const char *message);
 
 
 /**
diff --git a/src/include/gnunet_pq_lib.h b/src/include/gnunet_pq_lib.h
index 2cecb9885..1f2915165 100644
--- a/src/include/gnunet_pq_lib.h
+++ b/src/include/gnunet_pq_lib.h
@@ -1,6 +1,6 @@
 /*
    This file is part of GNUnet
-   Copyright (C) 2016, 2017, 2020 GNUnet e.V.
+   Copyright (C) 2016, 2017, 2020, 2021 GNUnet e.V.
 
    GNUnet is free software: you can redistribute it and/or modify it
    under the terms of the GNU Affero General Public License as published
@@ -853,6 +853,170 @@ GNUNET_PQ_reconnect (struct GNUNET_PQ_Context *db);
 
 
 /**
+ * Function called whenever the socket needed for 
+ * notifications from postgres changes.
+ *
+ * @param cls closure
+ * @param fd socket to listen on, -1 for none
+ */
+typedef void
+(*GNUNET_PQ_SocketCallback)(void *cls,
+                            int fd);
+
+
+/**
+ * Obtain the file descriptor to poll on for notifications.
+ * Useful if the GNUnet scheduler is NOT to be used for
+ * such notifications.
+ * 
+ * @param db database handle
+ * @param sc function to call with the socket
+ * @param sc_cls closure for @a sc
+ */
+void
+GNUNET_PQ_event_set_socket_callback (struct GNUNET_PQ_Context *db,
+                                     GNUNET_PQ_SocketCallback sc,
+                                     void *sc_cls);
+
+
+/**
+ * Poll for database events now.  Used if the event FD
+ * is ready and the application wants to trigger applicable
+ * events.
+ * Useful if the GNUnet scheduler is NOT to be used for
+ * such notifications.
+ *
+ * @param db database handle
+ */
+void
+GNUNET_PQ_event_do_poll (struct GNUNET_PQ_Context *db);
+
+
+/**
+ * Run poll event loop using the GNUnet scheduler.
+ *
+ * @param db database handle
+ */
+void
+GNUNET_PQ_event_scheduler_start (struct GNUNET_PQ_Context *db);
+
+
+/**
+ * Stop running poll event loop using the GNUnet scheduler.
+ *
+ * @param db database handle
+ */
+void
+GNUNET_PQ_event_scheduler_stop (struct GNUNET_PQ_Context *db);
+
+
+/**
+ * Handle for an active LISTENer to the database.
+ */ 
+struct GNUNET_PQ_EventHandler;
+
+/**
+ * Function called on events received from Postgres.
+ *
+ * @param cls closure
+ * @param extra additional event data provided
+ * @param extra_size number of bytes in @a extra
+ */
+typedef void
+(*GNUNET_PQ_EventCallback)(void *cls,
+                           const void *extra,
+                           size_t extra_size);
+
+GNUNET_NETWORK_STRUCT_BEGIN
+
+
+/**
+ * Header of a structure that describes an
+ * event channel we may subscribe to or notify on.
+ */
+struct GNUNET_PQ_EventHeaderP
+{
+  /**
+   * The length of the struct (in bytes, including the length field itself),
+   * in big-endian format.
+   */
+  uint16_t size GNUNET_PACKED;
+
+  /**
+   * The type of the message (GNUNET_PQ_EVENT_TYPE_XXXX), in big-endian format.
+   */
+  uint16_t type GNUNET_PACKED;
+
+};
+
+GNUNET_NETWORK_STRUCT_END
+
+
+/**
+ * Handle for an active LISTENer to the database.
+ */ 
+struct GNUNET_PQ_EventHandler;
+
+/**
+ * Register callback to be invoked on events of type @a es.
+ * 
+ * Unlike many other calls, this function is thread-safe
+ * and may be called from threads that are different
+ * from the one that setup @a db. However, the @a cb
+ * will always be called from the thread that runs
+ * #GNUNET_PQ_event_do_poll() or the GNUnet scheduler.
+ *
+ * @param db database context to use
+ * @param es specification of the event to listen for
+ * @param cb function to call when the event happens, possibly
+ *         multiple times (until #GNUNET_PQ_event_listen_cancel() is invoked)
+ * @param cb_cls closure for @a cb
+ * @return handle useful to cancel the listener
+ */
+struct GNUNET_PQ_EventHandler *
+GNUNET_PQ_event_listen (struct GNUNET_PQ_Context *db,
+                        const struct GNUNET_PQ_EventHeaderP *es,
+                        GNUNET_PQ_EventCallback cb,
+                        void *cb_cls);
+
+
+/**
+ * Stop notifications.
+ * 
+ * Unlike many other calls, this function is thread-safe
+ * and may be called from threads that are different
+ * from the one that setup @a db. However, the @a cb
+ * will always be called from the thread that runs
+ * #GNUNET_PQ_event_do_poll() or the GNUnet scheduler.
+ *
+ * @param eh handle to unregister.
+ */
+void
+GNUNET_PQ_event_listen_cancel (struct GNUNET_PQ_EventHandler *eh);
+
+
+/**
+ * Notify all that listen on @a es of an event.
+ * 
+ * Unlike many other calls, this function is thread-safe
+ * and may be called from threads that are different
+ * from the one that setup @a db. However, the @a cb
+ * will always be called from the thread that runs
+ * #GNUNET_PQ_event_do_poll() or the GNUnet scheduler.
+ *
+ * @param db database context to use
+ * @param es specification of the event to generate
+ * @param extra additional event data provided
+ * @param extra_size number of bytes in @a extra
+ */
+void
+GNUNET_PQ_event_notify (struct GNUNET_PQ_Context *db,
+                        const struct GNUNET_PQ_EventHeaderP *es,
+                        const void *extra,
+                        size_t extra_size);
+
+
+/**
  * Within the @a db context, run all the SQL files
  * from the @a load_path from 0000-9999.sql (as long
  * as the files exist contiguously).
@@ -861,7 +1025,7 @@ GNUNET_PQ_reconnect (struct GNUNET_PQ_Context *db);
  * @param load_path where to find the XXXX.sql files
  * @return #GNUNET_OK on success
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_PQ_run_sql (struct GNUNET_PQ_Context *db,
                    const char *load_path);
 
diff --git a/src/include/gnunet_strings_lib.h b/src/include/gnunet_strings_lib.h
index 955a3afca..977c2ead7 100644
--- a/src/include/gnunet_strings_lib.h
+++ b/src/include/gnunet_strings_lib.h
@@ -327,7 +327,7 @@ GNUNET_STRINGS_data_to_string_alloc (const void *buf,
  * @param out_size size of the output buffer @a out
  * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_STRINGS_string_to_data (const char *enc,
                                size_t enclen,
                                void *out,
@@ -335,6 +335,24 @@ GNUNET_STRINGS_string_to_data (const char *enc,
 
 
 /**
+ * Convert CrockfordBase32 encoding back to data.
+ * @a out_size will be determined from @a enc and
+ * @a out will be allocated to be large enough.
+ *
+ * @param enc the encoding
+ * @param enclen number of characters in @a enc (without 0-terminator, which can be missing)
+ * @param[out] out location where to allocate and store the decoded data
+ * @param[out] out_size set to the size of the output buffer @a out
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
+ */
+enum GNUNET_GenericReturnValue
+GNUNET_STRINGS_string_to_data_alloc (const char *enc,
+                                     size_t enclen,
+                                     void **out,
+                                     size_t *out_size);
+
+
+/**
  * Encode into Base64.
  *
  * @param data the data to encode
@@ -359,7 +377,10 @@ GNUNET_STRINGS_base64_encode (const void *in,
  * @return the size of the output
  */
 size_t
-GNUNET_STRINGS_urlencode (const char *data, size_t len, char **out);
+GNUNET_STRINGS_urlencode (const char *data,
+                          size_t len,
+                          char **out);
+
 
 /**
  * Encode into Base64url. RFC7515
@@ -371,7 +392,9 @@ GNUNET_STRINGS_urlencode (const char *data, size_t len, char **out);
  * @return the size of the output
  */
 size_t
-GNUNET_STRINGS_base64url_encode (const void *in, size_t len, char **output);
+GNUNET_STRINGS_base64url_encode (const void *in,
+                                 size_t len,
+                                 char **output);
 
 
 /**
@@ -399,7 +422,9 @@ GNUNET_STRINGS_base64_decode (const char *data,
  * @return the size of the output
  */
 size_t
-GNUNET_STRINGS_base64url_decode (const char *data, size_t len, void **out);
+GNUNET_STRINGS_base64url_decode (const char *data,
+                                 size_t len,
+                                 void **out);
 
 /**
  * url/percent encode (RFC3986).
@@ -411,7 +436,9 @@ GNUNET_STRINGS_base64url_decode (const char *data, size_t len, void **out);
  * @return the size of the output
  */
 size_t
-GNUNET_STRINGS_urldecode (const char *data, size_t len, char **out);
+GNUNET_STRINGS_urldecode (const char *data,
+                          size_t len,
+                          char **out);
 
 
 /**
@@ -442,7 +469,7 @@ GNUNET_STRINGS_pp2s (const struct GNUNET_PeerIdentity *pids,
  *         an URI, '* scheme_part' and '*path_part' will remain unchanged
  *         (if they weren't NULL).
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_STRINGS_parse_uri (const char *path,
                           char **scheme_part,
                           const char **path_part);
@@ -462,7 +489,7 @@ GNUNET_STRINGS_parse_uri (const char *path,
  *        GNUNET_free (). Can be NULL.
  * @return #GNUNET_YES if 'filename' is absolute, #GNUNET_NO otherwise.
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_STRINGS_path_is_absolute (const char *filename,
                                  int can_be_uri,
                                  int *r_is_uri,
@@ -505,7 +532,7 @@ enum GNUNET_STRINGS_FilenameCheck
  * @return #GNUNET_YES if all checks pass, #GNUNET_NO if at least one of them
  *         fails, #GNUNET_SYSERR when a check can't be performed
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_STRINGS_check_filename (const char *filename,
                                enum GNUNET_STRINGS_FilenameCheck checks);
 
@@ -521,7 +548,7 @@ GNUNET_STRINGS_check_filename (const char *filename,
  * @return #GNUNET_OK if conversion succeeded. #GNUNET_SYSERR otherwise, in which
  *         case the contents of r_buf are undefined.
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_STRINGS_to_address_ipv6 (const char *zt_addr,
                                 uint16_t addrlen,
                                 struct sockaddr_in6 *r_buf);
@@ -537,7 +564,7 @@ GNUNET_STRINGS_to_address_ipv6 (const char *zt_addr,
  * @return #GNUNET_OK if conversion succeeded. #GNUNET_SYSERR otherwise, in which case
  *         the contents of r_buf are undefined.
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_STRINGS_to_address_ipv4 (const char *zt_addr,
                                 uint16_t addrlen,
                                 struct sockaddr_in *r_buf);
@@ -569,7 +596,7 @@ GNUNET_STRINGS_parse_socket_addr (const char *addr,
  * @return #GNUNET_OK if conversion succeeded. #GNUNET_SYSERR otherwise, in which
  *         case the contents of r_buf are undefined.
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_STRINGS_to_address_ip (const char *addr,
                               uint16_t addrlen,
                               struct sockaddr_storage *r_buf);
@@ -587,7 +614,7 @@ GNUNET_STRINGS_to_address_ip (const char *addr,
  * @param u8argv a location to store new argv in
  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_STRINGS_get_utf8_args (int argc,
                               char *const *argv,
                               int *u8argc,
@@ -610,7 +637,9 @@ GNUNET_STRINGS_get_utf8_args (int argc,
  *         null byte
  */
 size_t
-GNUNET_strlcpy (char *dst, const char *src, size_t n);
+GNUNET_strlcpy (char *dst,
+                const char *src,
+                size_t n);
 
 
 /* ***************** IPv4/IPv6 parsing ****************** */