more work on plugins

2 files changed, 77 insertions, 17 deletions

diff --git a/include/macros.h b/include/macros.h
index b7a1bd2..6d093d7 100644
--- a/include/macros.h
+++ b/include/macros.h
@@ -6,25 +6,17 @@
 #define UNUSED(...) ((void)((void) __VA_ARGS__))
 #define NO_OP_DECL _Static_assert(1, "")
 
-#ifdef __has_attribute
-# if __has_attribute(unavailable)
-#  define PTX_UNAVAILABLE(_x) __attribute__((unavailable(_x)))
-#  define PTX_UNAVAILABLE_DEF(_x, _def) _def PTX_UNAVAILABLE(_x)
-# else
-#  define PTX_UNAVAILABLE(_x)
-#  define PTX_UNAVAILABLE_DEF(_x, _def) /* definition hidden */ NO_OP_DECL
-# endif
-#else
-# define PTX_UNAVAILABLE(_x)
-# define PTX_UNAVAILABLE_DEF(_x, _def) /* definition hidden */ NO_OP_DECL
-#endif
+#define PTX_UNAVAILABLE_DEF(_def) /* definition hidden */ NO_OP_DECL
 
 #ifdef PTX_PLUGIN
 #define PTX_API PTX_IMPORT
-#define PTX_INTERNAL(_def) PTX_UNAVAILABLE_DEF("internal API", _def)
+#define PTX_INTERNAL(_def) NO_OP_DECL
 #else
 #define PTX_API PTX_EXPORT
 #define PTX_INTERNAL(_def) _def
 #endif
 
+#define PTX_STR(_x) PTX_STR2(_x)
+#define PTX_STR2(_x) #_x
+
 #endif /* include guard */
diff --git a/include/plugins.h b/include/plugins.h
index f6865e5..cbd841d 100644
--- a/include/plugins.h
+++ b/include/plugins.h
@@ -1,24 +1,92 @@
 #ifndef PTX_PLUGINS_H_INCLUDED
 #define PTX_PLUGINS_H_INCLUDED
 
+#include <stddef.h>
 #include "macros.h"
 
 typedef struct ptx__plugin_manager_tag ptx_plugin_manager_t;
 typedef struct ptx__plugin_handle_tag ptx_plugin_t;
 
+/* returns:
+ * - < 0 for plugin loading error (plugin will not be loaded)
+ * - 0 for successful plugin startup
+ * - (don't return values greater than 0 at this time)
+ * usage:
+ * Function will be called with this plugin instance and the "resume" pointer.
+ *
+ * The "resume" pointer will be NULL if the plugin is not being resumed. For this reason, it is not advised
+ * to use NULL as a flag value in the restart function itself.
+ */
+typedef int (ptx_plugin_init_proc_t)(ptx_plugin_t * /*plugin*/, void * /*resume*/);
+
+enum {
+  /* This plugin cannot be resumed at this time. The plugin manager will not unload it if it expects a "seamless" reload.
+   * The plugin is expected to act as if this function was not called. */
+  PTX_PLUGIN_CANNOT_RESUME = -1,
+
+  /* The plugin supports being resumed, but due to a transient error condition (malloc failure?) the plugin could not set itself up for
+   * resuming. If a plugin returns this value to the plugin manager, it is expected to act as if the function was not called. */
+  PTX_PLUGIN_RESUME_ERR = -2,
+
+  /* The plugin supports being resumed, but due to a transient error condition, the plugin could not set itself up for resuming.
+   * Additionally, as a part of preparing to be reloaded, the plugin performed operations it could not roll back. Likely, an error
+   * will be reported to the user, and the plugin will be unloaded. The plugin manager makes no assumptions about the behavior of the
+   * plugin at this time. */
+  PTX_PLUGIN_RESUME_ERR_UNRECOVERABLE = -3,
+
+  /* The plugin is ready to be resumed. */
+  PTX_PLUGIN_RESUME_OK = 0
+};
+
+/* returns:
+ * - one of the PTX_PLUGIN_* values in the above enum. if the return value is anything else, the plugin manager's behavior is not defined.
+ */
+typedef int (ptx_plugin_restart_proc_t)(ptx_plugin_t * /*plugin*/, void ** /*presume*/);
+
+#define PTX_MOD_VERSION (1u)
+
+/* the fields of this struct are public. ABI changes should be marked by incrementing PTX_MOD_VERSION */
+struct ptx_plugin_desc
+{
+  size_t desc_len;
+  unsigned desc_ver;
+  unsigned reserved;
+
+  ptx_plugin_init_proc_t *init_proc;
+  ptx_plugin_restart_proc_t *restart_proc;
+
+  const char *name;
+  const char *description;
+  const char *version;
+};
+
 /* for testing */
 #ifdef _CLANGD
 #undef PTX_PLUGIN
 #define PTX_PLUGIN 1
 #endif
 
-PTX_INTERNAL(ptx_plugin_manager_t *ptx_plugin_manager_new(void) ATTR_MALLOC() ATTR_MALLOC((ptx_plugin_manager_free, 1)) ATTR_WUR);
-PTX_INTERNAL(void ptx_plugin_manager_free(ptx_plugin_manager_t *mgr));
-
-PTX_INTERNAL(int ptx_plugin_manager_load_dir(ptx_plugin_manager_t *mgr, const char *dir));
+#define PTX__INTERNAL_PLUGIN_DESC_SYM ptx__plugin_spec
 
 #ifdef PTX_PLUGIN
+#define PTX_PLUGIN_DESC_START PTX_EXPORT \
+  const struct ptx_plugin_desc PTX__INTERNAL_PLUGIN_DESC_SYM = { \
+    .desc_len = sizeof(struct ptx_plugin_desc), \
+    .desc_ver = PTX_MOD_VERSION,
+
+#define PTX_PLUGIN_NAME(_x)        .name = _x,
+#define PTX_PLUGIN_DESCRIPTION(_x) .description = _x,
+#define PTX_PLUGIN_VERSION(_x)     .version = _x,
+
+#define PTX_PLUGIN_INIT(_x)        .init_proc = _x,
+#define PTX_PLUGIN_RESTART(_x)     .restart_proc = _x,
 
+#define PTX_PLUGIN_DESC_END };
 #endif
 
+PTX_INTERNAL(ptx_plugin_manager_t *ptx_plugin_manager_new(void) ATTR_MALLOC() ATTR_MALLOC((ptx_plugin_manager_free, 1)) ATTR_WUR);
+PTX_INTERNAL(void ptx_plugin_manager_free(ptx_plugin_manager_t *mgr));
+
+PTX_INTERNAL(int ptx_plugin_manager_load_dir(ptx_plugin_manager_t *mgr, const char *dir));
+
 #endif