aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_pq_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_pq_lib.h')
-rw-r--r--src/include/gnunet_pq_lib.h168
1 files changed, 166 insertions, 2 deletions
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 @@
1/* 1/*
2 This file is part of GNUnet 2 This file is part of GNUnet
3 Copyright (C) 2016, 2017, 2020 GNUnet e.V. 3 Copyright (C) 2016, 2017, 2020, 2021 GNUnet e.V.
4 4
5 GNUnet is free software: you can redistribute it and/or modify it 5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published 6 under the terms of the GNU Affero General Public License as published
@@ -853,6 +853,170 @@ GNUNET_PQ_reconnect (struct GNUNET_PQ_Context *db);
853 853
854 854
855/** 855/**
856 * Function called whenever the socket needed for
857 * notifications from postgres changes.
858 *
859 * @param cls closure
860 * @param fd socket to listen on, -1 for none
861 */
862typedef void
863(*GNUNET_PQ_SocketCallback)(void *cls,
864 int fd);
865
866
867/**
868 * Obtain the file descriptor to poll on for notifications.
869 * Useful if the GNUnet scheduler is NOT to be used for
870 * such notifications.
871 *
872 * @param db database handle
873 * @param sc function to call with the socket
874 * @param sc_cls closure for @a sc
875 */
876void
877GNUNET_PQ_event_set_socket_callback (struct GNUNET_PQ_Context *db,
878 GNUNET_PQ_SocketCallback sc,
879 void *sc_cls);
880
881
882/**
883 * Poll for database events now. Used if the event FD
884 * is ready and the application wants to trigger applicable
885 * events.
886 * Useful if the GNUnet scheduler is NOT to be used for
887 * such notifications.
888 *
889 * @param db database handle
890 */
891void
892GNUNET_PQ_event_do_poll (struct GNUNET_PQ_Context *db);
893
894
895/**
896 * Run poll event loop using the GNUnet scheduler.
897 *
898 * @param db database handle
899 */
900void
901GNUNET_PQ_event_scheduler_start (struct GNUNET_PQ_Context *db);
902
903
904/**
905 * Stop running poll event loop using the GNUnet scheduler.
906 *
907 * @param db database handle
908 */
909void
910GNUNET_PQ_event_scheduler_stop (struct GNUNET_PQ_Context *db);
911
912
913/**
914 * Handle for an active LISTENer to the database.
915 */
916struct GNUNET_PQ_EventHandler;
917
918/**
919 * Function called on events received from Postgres.
920 *
921 * @param cls closure
922 * @param extra additional event data provided
923 * @param extra_size number of bytes in @a extra
924 */
925typedef void
926(*GNUNET_PQ_EventCallback)(void *cls,
927 const void *extra,
928 size_t extra_size);
929
930GNUNET_NETWORK_STRUCT_BEGIN
931
932
933/**
934 * Header of a structure that describes an
935 * event channel we may subscribe to or notify on.
936 */
937struct GNUNET_PQ_EventHeaderP
938{
939 /**
940 * The length of the struct (in bytes, including the length field itself),
941 * in big-endian format.
942 */
943 uint16_t size GNUNET_PACKED;
944
945 /**
946 * The type of the message (GNUNET_PQ_EVENT_TYPE_XXXX), in big-endian format.
947 */
948 uint16_t type GNUNET_PACKED;
949
950};
951
952GNUNET_NETWORK_STRUCT_END
953
954
955/**
956 * Handle for an active LISTENer to the database.
957 */
958struct GNUNET_PQ_EventHandler;
959
960/**
961 * Register callback to be invoked on events of type @a es.
962 *
963 * Unlike many other calls, this function is thread-safe
964 * and may be called from threads that are different
965 * from the one that setup @a db. However, the @a cb
966 * will always be called from the thread that runs
967 * #GNUNET_PQ_event_do_poll() or the GNUnet scheduler.
968 *
969 * @param db database context to use
970 * @param es specification of the event to listen for
971 * @param cb function to call when the event happens, possibly
972 * multiple times (until #GNUNET_PQ_event_listen_cancel() is invoked)
973 * @param cb_cls closure for @a cb
974 * @return handle useful to cancel the listener
975 */
976struct GNUNET_PQ_EventHandler *
977GNUNET_PQ_event_listen (struct GNUNET_PQ_Context *db,
978 const struct GNUNET_PQ_EventHeaderP *es,
979 GNUNET_PQ_EventCallback cb,
980 void *cb_cls);
981
982
983/**
984 * Stop notifications.
985 *
986 * Unlike many other calls, this function is thread-safe
987 * and may be called from threads that are different
988 * from the one that setup @a db. However, the @a cb
989 * will always be called from the thread that runs
990 * #GNUNET_PQ_event_do_poll() or the GNUnet scheduler.
991 *
992 * @param eh handle to unregister.
993 */
994void
995GNUNET_PQ_event_listen_cancel (struct GNUNET_PQ_EventHandler *eh);
996
997
998/**
999 * Notify all that listen on @a es of an event.
1000 *
1001 * Unlike many other calls, this function is thread-safe
1002 * and may be called from threads that are different
1003 * from the one that setup @a db. However, the @a cb
1004 * will always be called from the thread that runs
1005 * #GNUNET_PQ_event_do_poll() or the GNUnet scheduler.
1006 *
1007 * @param db database context to use
1008 * @param es specification of the event to generate
1009 * @param extra additional event data provided
1010 * @param extra_size number of bytes in @a extra
1011 */
1012void
1013GNUNET_PQ_event_notify (struct GNUNET_PQ_Context *db,
1014 const struct GNUNET_PQ_EventHeaderP *es,
1015 const void *extra,
1016 size_t extra_size);
1017
1018
1019/**
856 * Within the @a db context, run all the SQL files 1020 * Within the @a db context, run all the SQL files
857 * from the @a load_path from 0000-9999.sql (as long 1021 * from the @a load_path from 0000-9999.sql (as long
858 * as the files exist contiguously). 1022 * as the files exist contiguously).
@@ -861,7 +1025,7 @@ GNUNET_PQ_reconnect (struct GNUNET_PQ_Context *db);
861 * @param load_path where to find the XXXX.sql files 1025 * @param load_path where to find the XXXX.sql files
862 * @return #GNUNET_OK on success 1026 * @return #GNUNET_OK on success
863 */ 1027 */
864int 1028enum GNUNET_GenericReturnValue
865GNUNET_PQ_run_sql (struct GNUNET_PQ_Context *db, 1029GNUNET_PQ_run_sql (struct GNUNET_PQ_Context *db,
866 const char *load_path); 1030 const char *load_path);
867 1031