raft.h: Add struct raft_task to track asynchronous tasks (#57)

The new `struct raft_task` structure and the associated `struct
raft->tasks` queue will be used in the pull-based v1 API to inform
consumers of what operations they need to carry.

include/raft.h

@@ -11,6 +11,11 @@
 #define RAFT_API __attribute__((visibility("default")))
 #endif
 
+/* Helper for statically checking ABI compatibility when changing or adding
+ * struct fields. */
+#define RAFT__ASSERT_COMPATIBILITY(OLD_FIELDS, NEW_FIELDS) \
+    _Static_assert(sizeof(NEW_FIELDS) <= sizeof(OLD_FIELDS), "ABI breakage")
+
 /**
  * Version.
  */
@@ -62,6 +67,9 @@ enum {
  */
 RAFT_API const char *raft_strerror(int errnum);
 
+/**
+ * Hold the value of a raft server ID. Guaranteed to be at least 64-bit long.
+ */
 typedef unsigned long long raft_id;
 
 /**
@@ -79,11 +87,6 @@ typedef unsigned long long raft_index;
  */
 typedef unsigned long long raft_time;
 
-/* Helper for statically checking ABI compatibility when changing or adding
- * struct fields. */
-#define RAFT__ASSERT_COMPATIBILITY(OLD_FIELDS, NEW_FIELDS) \
-    _Static_assert(sizeof(NEW_FIELDS) <= sizeof(OLD_FIELDS), "ABI breakage")
-
 /**
  * Hold the features a raft node is capable of.
  */
@@ -538,6 +541,30 @@ typedef void (*raft_io_recv_cb)(struct raft_io *io, struct raft_message *msg);
 
 typedef void (*raft_io_close_cb)(struct raft_io *io);
 
+/**
+ * Type codes for async tasks issued by #raft and that must be completed by
+ * consumers.
+ */
+enum {
+    RAFT_SEND_MESSAGE = 1,
+    RAFT_PERSIST_ENTRIES,
+    RAFT_PERSIST_TERM_AND_VOTE,
+    RAFT_PERSIST_SNAPSHOT,
+    RAFT_LOAD_SNAPSHOT,
+    RAFT_APPLY_COMMAND,
+    RAFT_TAKE_SNAPSHOT,
+    RAFT_RESTORE_SNAPSHOT
+};
+
+/**
+ * Represents a task that can be queued and executed asynchronously.
+ */
+struct raft_task
+{
+    unsigned char type;
+    unsigned char reserved[7];
+};
+
 /**
  * version field MUST be filled out by user.
  * When moving to a new version, the user MUST implement the newly added
@@ -651,11 +678,14 @@ struct raft_log;
     }
 
 /* Extended struct raft fields added after the v0.x ABI freeze. */
-#define RAFT__EXTENSIONS                                             \
-    struct                                                           \
-    {                                                                \
-        raft_time now;   /* Current time, updated via raft_step() */ \
-        unsigned random; /* Pseudo-random number generator state */  \
+#define RAFT__EXTENSIONS                                                     \
+    struct                                                                   \
+    {                                                                        \
+        raft_time now;           /* Current time, updated via raft_step() */ \
+        unsigned random;         /* Pseudo-random number generator state */  \
+        struct raft_task *tasks; /* Queue of pending raft_task operations */ \
+        unsigned n_tasks;        /* Length of the task queue */              \
+        unsigned n_tasks_cap;    /* Capacity of the task queue */            \
     }
 
 RAFT__ASSERT_COMPATIBILITY(RAFT__RESERVED, RAFT__EXTENSIONS);

src/raft.c

@@ -103,6 +103,9 @@ int raft_init(struct raft *r,
     }
     r->now = r->io->time(r->io);
     raft_seed(r, (unsigned)r->io->random(r->io, 0, INT_MAX));
+    r->tasks = NULL;
+    r->n_tasks = 0;
+    r->n_tasks_cap = 0;
     return 0;
 
 err_after_address_alloc:
@@ -131,6 +134,9 @@ void raft_close(struct raft *r, void (*cb)(struct raft *r))
     if (r->state != RAFT_UNAVAILABLE) {
         convertToUnavailable(r);
     }
+    if (r->tasks != NULL) {
+        raft_free(r->tasks);
+    }
     r->close_cb = cb;
     r->io->close(r->io, ioCloseCb);
 }