Event service extension specfication

Refs #61

wsrep_event_service.h

@@ -0,0 +1,157 @@
+/*
+ * Copyright (C) 2021 Codership Oy <[email protected]>
+ *
+ * This file is part of wsrep-API.
+ *
+ * Wsrep-API is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * Wsrep-API is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with wsrep-API.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/** @file wsrep_event_service.h
+ *
+ * This file defines interface for various unordered events generated by the
+ * cluster or the provider.
+ *
+ * An event has a type and a payload. The type can be predefined or generic.
+ * In the first case the payload is a POD C struct. Generic event is a JSON-
+ * encoded buffer.
+ *
+ * The provider which is capable of using the service interface v1 must
+ * export the following functions.
+ *
+ * int wsrep_init_event_service_v1(wsrep_event_service_v1_t*)
+ * void wsrep_deinit_event_service_v1()
+ *
+ * which can be probed by the application.
+ *
+ * The application must initialize the service via above init function
+ * before the provider is initialized via wsrep->init(). The deinit
+ * function must be called after the provider side resources have been
+ * released via wsrep->free().
+ */
+
+#ifndef WSREP_EVENT_SERVICE_H
+#define WSREP_EVENT_SERVICE_H
+
+#include "wsrep_api.h"
+
+#include <sys/types.h> /* posix size_t */
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif /* __cplusplus */
+
+/**
+ * Type tag for application defined event processing context.
+ *
+ * Application may pass pointer to the context when initializing
+ * the event service. This pointer is passed a first parameter for
+ * each service call.
+ */
+typedef struct wsrep_event_context wsrep_event_context_t;
+
+
+/**
+ * Event types: generic and concrete
+ */
+typedef enum wsrep_event_type
+{
+    /**
+     * Generic JSON-encoded event type.
+     */
+    wsrep_event_generic,
+    /**
+     * Progress event.
+     */
+    wsrep_event_progress
+}
+wsrep_event_type_t;
+
+
+/**
+ * Progress event structure
+ */
+typedef struct wsrep_event_st
+{
+    wsrep_buf_t payload;
+    wsrep_event_type_t type;
+}
+wsrep_event_t;
+
+
+/**
+ * Progress event structure
+ */
+typedef struct wsrep_event_progress_st
+{
+    /**
+     * Total amount of work to do.
+     */
+    uint64_t total;
+    /**
+     * Amount of work already done.
+     */
+    uint64_t done;
+    /**
+     * Current node state
+     */
+    wsrep_member_status_t status;
+}
+wsrep_event_progress_t;
+
+/**
+ * Indefinite progress value when the progress cannot be assessed
+ */
+static float const wsrep_event_progress_indefinite = -1.0f;
+
+
+/**
+ * Process an event
+ *
+ * @param event.
+ *
+ * @return void, it is up to the receiver to decide what to do about
+ *         possible error.
+ */
+typedef void (*wsrep_event_cb_t)(wsrep_event_context_t*,
+                                 const wsrep_event_t*);
+
+
+/**
+ * Event service struct.
+ *
+ * A pointer to this struct must be passed to the call to
+ * wsrep_init_event_service_v1.
+ *
+ * The application must provide implementation to all functions defined
+ * in this struct.
+ */
+typedef struct wsrep_event_service_v1_st
+{
+    /* Event receiver callback */
+    wsrep_event_cb_t event_cb;
+    /* Pointer to application defined event context. */
+    wsrep_event_context_t* context;
+} wsrep_event_service_v1_t;
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+
+#define WSREP_EVENT_SERVICE_INIT_FUNC_V1 "wsrep_init_event_service_v1"
+#define WSREP_EVENT_SERVICE_DEINIT_FUNC_V1 "wsrep_deinit_event_service_v1"
+
+#endif /* WSREP_EVENT_SERVICE_H */
+