Add ABI for tracking events

.unreleased/pr_7791

@@ -0,0 +1 @@
+Implements: #7791 ABI for tracking TimescaleDB events

src/CMakeLists.txt

@@ -109,6 +109,12 @@ if(USE_OPENSSL)
   endif(MSVC)
 endif(USE_OPENSSL)
 
+# This is a kind of strange usage, but it follows the convention of
+# PG_VERSION_NUM, where you can get the major version by dividing by 100.
+# However, the major number shows up as, e.g., 1500 for PostgreSQL version 15.
+math(EXPR TS_VERSION_NUM
+     "${PROJECT_VERSION_MAJOR} * 10000 + ${PROJECT_VERSION_MINOR}")
+
 configure_file(config.h.in config.h)
 add_dependencies(${PROJECT_NAME} gitcheck)
 include_directories(${CMAKE_CURRENT_SOURCE_DIR})

src/bgw/job.c

@@ -1170,6 +1170,12 @@ ts_bgw_job_entrypoint(PG_FUNCTION_ARGS)
 		callbacks->toggle_allocation_blocking && !callbacks->enabled)
 		callbacks->toggle_allocation_blocking(/*enable=*/true);
 
+	TS_PLUGIN_CALLBACK(*timescaledb_plugin_ptr,
+					   bgw_job_starting,
+					   db_oid,
+					   params.job_id,
+					   params.user_oid);
+
 	BackgroundWorkerInitializeConnectionByOid(db_oid, params.user_oid, 0);
 
 	log_min_messages = ts_guc_bgw_log_level;
@@ -1287,6 +1293,11 @@ ts_bgw_job_entrypoint(PG_FUNCTION_ARGS)
 
 		CommitTransactionCommand();
 		FlushErrorState();
+		TS_PLUGIN_CALLBACK(*timescaledb_plugin_ptr,
+						   bgw_job_exiting,
+						   db_oid,
+						   params.job_id,
+						   JOB_FAILURE_IN_EXECUTION);
 		ReThrowError(edata);
 	}
 	PG_END_TRY();
@@ -1312,6 +1323,8 @@ ts_bgw_job_entrypoint(PG_FUNCTION_ARGS)
 	INSTR_TIME_SET_CURRENT(duration);
 	INSTR_TIME_SUBTRACT(duration, start);
 
+	TS_PLUGIN_CALLBACK(*timescaledb_plugin_ptr, bgw_job_exiting, db_oid, params.job_id, res);
+
 	elog(DEBUG1,
 		 "job %d (%s) exiting with %s: execution time %.2f ms",
 		 params.job_id,

src/bgw/job.h

@@ -6,6 +6,7 @@
 #pragma once
 
 #include <postgres.h>
+#include <fmgr.h>
 #include <postmaster/bgworker.h>
 #include <storage/lock.h>
 

src/config.h.in

@@ -11,6 +11,7 @@
 #define BUILD_OS_VERSION "@CMAKE_SYSTEM_VERSION@"
 #define BUILD_PROCESSOR "@CMAKE_SYSTEM_PROCESSOR@"
 #define BUILD_POINTER_BYTES @CMAKE_SIZEOF_VOID_P@
+#define TS_VERSION_NUM @TS_VERSION_NUM@
 
 /*
  * Value should be set in package release scripts. Otherwise

src/extension.h

@@ -10,6 +10,7 @@
 
 #include "export.h"
 #include "extension_constants.h"
+#include "timescaledb.h"
 
 extern void ts_extension_invalidate(void);
 extern TSDLLEXPORT bool ts_extension_is_loaded(void);
@@ -21,3 +22,5 @@ extern TSDLLEXPORT char *ts_extension_schema_name(void);
 extern const char *ts_experimental_schema_name(void);
 extern const char *ts_extension_get_so_name(void);
 extern bool ts_extension_is_proxy_table_relid(Oid relid);
+
+extern TimescaleDBPlugin **timescaledb_plugin_ptr;

src/init.c

@@ -19,13 +19,16 @@
 #include "guc.h"
 #include "license_guc.h"
 #include "nodes/constraint_aware_append/constraint_aware_append.h"
+#include "timescaledb.h"
 #include "ts_catalog/catalog.h"
 #include "version.h"
 
 #ifdef PG_MODULE_MAGIC
 PG_MODULE_MAGIC;
 #endif
 
+TimescaleDBPlugin **timescaledb_plugin_ptr = NULL;
+
 extern void _hypertable_cache_init(void);
 extern void _hypertable_cache_fini(void);
 
@@ -92,6 +95,12 @@ void
 _PG_init(void)
 {
 	static bool init_done = false;
+	static TimescaleDBPlugin timescaledb_plugin_var = {
+		.size = sizeof(TimescaleDBPlugin),
+		.magic = PG_MODULE_MAGIC_DATA,
+		.pg_version = PG_VERSION_NUM,
+		.ts_version = TS_VERSION_NUM,
+	};
 
 	/*
 	 * Check extension_is loaded to catch certain errors such as calls to
@@ -107,6 +116,12 @@ _PG_init(void)
 	if (init_done)
 		return;
 
+	timescaledb_plugin_ptr =
+		(TimescaleDBPlugin **) find_rendezvous_variable(TIMESCALEDB_PLUGIN_NAME);
+	/* We're the first, so set up the structure */
+	if (*timescaledb_plugin_ptr == NULL)
+		*timescaledb_plugin_ptr = &timescaledb_plugin_var;
+
 	_cache_init();
 	_hypertable_cache_init();
 	_cache_invalidate_init();

src/timescaledb.c

@@ -0,0 +1,23 @@
+/*
+ * This file and its contents are licensed under the Apache License 2.0.
+ * Please see the included NOTICE for copyright information and
+ * LICENSE-APACHE for a copy of the license.
+ */
+#include <postgres.h>
+
+#include "planner/planner.h"
+#include "timescaledb.h"
+#include <c.h>
+
+/*
+ * This file contains function and support for dealing with the ABI. See the
+ * header file for more information.
+ */
+
+/* Structure to go from old definition in mem_guard to the TimescaleDB plugin
+   structure defined in the header file. */
+static TimescaleDBPlugin plugin_callbacks = {
+	.magic = PG_MODULE_MAGIC_DATA,
+	.pg_version = PG_VERSION_NUM,
+	.ts_version = TS_VERSION_NUM,
+};

src/timescaledb.h

@@ -0,0 +1,63 @@
+/*
+ * This file and its contents are licensed under the Apache License 2.0.
+ * Please see the included NOTICE for copyright information and
+ * LICENSE-APACHE for a copy of the license.
+ */
+
+/*
+ * File with definitions intended for plugins that want to interact with TimescaleDB.
+ *
+ * WARNING! Do not add variables, functions, macros, or other stuff that is
+ * not intended for an external user, e.g., a separate plugin.
+ */
+#pragma once
+
+#include <postgres.h>
+#include <fmgr.h>
+
+/*
+ * Plugin structure with callbacks.
+ *
+ * Other plugins can use this to get information about the running version of
+ * TimescaleDB as well as callbacks on particular events.
+ *
+ * IMPORTANT: If you extend this structure, take care to not remove any fields
+ * and add new fields last. If you do not do this, you might break plugins
+ * that are using the wrong version and read some field that you moved or
+ * deleted.
+ */
+typedef struct TimescaleDBPlugin
+{
+	size_t size;		   /* Size of this structure */
+	Pg_magic_struct magic; /* Pointer to PostgreSQL magic */
+	int pg_version;		   /* PostgreSQL version as a number */
+	int ts_version;		   /* TimescaleDB version as a number */
+
+	/*
+	 * Plugins can fill this in and get callbacks on particular events.
+	 */
+	void (*bgw_job_starting)(Oid db_id, int32 job_id, Oid user_oid);
+	void (*bgw_job_exiting)(Oid db_id, int job_id, int result);
+} TimescaleDBPlugin;
+
+#define TIMESCALEDB_PLUGIN_NAME "TimescaleDBPlugin"
+
+/*
+ * Convenience macro for plugin callback.
+ *
+ * The expands to a check if: the plugin pointer is non-zero, the offset of
+ * the function pointer is inside the structure, and the function pointer is
+ * non-zero.
+ *
+ * If either is false, this is effectively a no-op.
+ *
+ * The check that the pointer is inside the size of the structure allows you
+ * to add new functions to the structure without risking a call to a random
+ * location if the structure is too "old" for the call.
+ */
+#define TS_PLUGIN_CALLBACK(PTR, FUNC, ...)                                                         \
+	do                                                                                             \
+	{                                                                                              \
+		if ((PTR) && offsetof(TimescaleDBPlugin, FUNC) < (PTR)->size && (PTR)->FUNC)               \
+			(*(PTR)->FUNC)(__VA_ARGS__);                                                           \
+	} while (0)