Asynchronous communication

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 200 insertions, 26 deletions

diff --git a/src/libcoopgamma.h b/src/libcoopgamma.h
index 9c33646..cbea817 100644
--- a/src/libcoopgamma.h
+++ b/src/libcoopgamma.h
@@ -128,6 +128,13 @@
  */
 #define LIBCOOPGAMMA_CONTEXT_VERSION  0
 
+/**
+ * Number used to identify implementation
+ * version of `libcoopgamma_async_context_t`, if it
+ * is ever modified, this number is increased
+ */
+#define LIBCOOPGAMMA_ASYNC_CONTEXT_VERSION  0
+
 
 
 /**
@@ -595,6 +602,10 @@ typedef struct libcoopgamma_error
 
 /**
  * Library state
+ * 
+ * Use of this structure is not thread-safe,
+ * create one instance per thread that uses
+ * this structure
  */
 typedef struct libcoopgamma_context
 {
@@ -615,9 +626,64 @@ typedef struct libcoopgamma_context
    */
   uint32_t message_id;
   
+  /**
+   * Buffer with the outbound message
+   */
+  char* outbound;
+  
+  /**
+   * The write head for `outbound`
+   */
+  size_t outbound_head;
+  
+  /**
+   * The read head for `outbound`
+   */
+  size_t outbound_tail;
+  
+  /**
+   * The allocation size of `outbound`
+   */
+  size_t outbound_size;
+  
+  /**
+   * Buffer with the inbound message
+   */
+  char* inbound;
+  
+  /**
+   * The write head for `inbound`
+   */
+  size_t inbound_head;
+  
+  /**
+   * The read head for `inbound`
+   */
+  size_t inbound_tail;
+  
+  /**
+   * The allocation size of `inbound`
+   */
+  size_t inbound_size;
+  
 } libcoopgamma_context_t;
 
 
+/**
+ * Information necessary to identify and
+ * parse a response from the server
+ */
+typedef struct libcoopgamma_async_context
+{
+  /**
+   * The value of the 'In response to' header
+   * in the waited message
+   */
+  uint32_t message_id;
+  
+} libcoopgamma_async_context_t;
+
+
 
 /**
  * Initialise a `libcoopgamma_ramps8_t`, `libcoopgamma_ramps16_t`, `libcoopgamma_ramps32_t`,
@@ -1012,6 +1078,49 @@ int libcoopgamma_context_unmarshal(libcoopgamma_context_t* restrict, const void*
 
 
 /**
+ * Initialise a `libcoopgamma_async_context_t`
+ * 
+ * @param   this  The record to initialise
+ * @return        Zero on success, -1 on error
+ */
+int libcoopgamma_async_context_initialise(libcoopgamma_async_context_t* restrict);
+
+/**
+ * Release all resources allocated to  a `libcoopgamma_async_context_t`,
+ * the allocation of the record itself is not freed
+ * 
+ * Always call this function after failed call to `libcoopgamma_async_context_initialise`
+ * or failed call to `libcoopgamma_async_context_unmarshal`
+ * 
+ * @param  this  The record to destroy
+ */
+void libcoopgamma_async_context_destroy(libcoopgamma_async_context_t* restrict);
+
+/**
+ * Marshal a `libcoopgamma_async_context_t` into a buffer
+ * 
+ * @param   this  The record to marshal
+ * @param   buf   The output buffer, `NULL` to only measure
+ *                how large this buffer has to be
+ * @return        The number of marshalled bytes, or if `buf == NULL`,
+ *                how many bytes would be marshalled if `buf != NULL`
+ */
+size_t libcoopgamma_async_context_marshal(const libcoopgamma_async_context_t* restrict, void* restrict);
+
+/**
+ * Unmarshal a `libcoopgamma_async_context_t` from a buffer
+ * 
+ * @param   this  The output paramater for unmarshalled record
+ * @param   buf   The buffer with the marshalled record
+ * @param   n     Output parameter for the number of unmarshalled bytes, undefined on failure
+ * @return        `LIBCOOPGAMMA_SUCCESS` (0), `LIBCOOPGAMMA_INCOMPATIBLE_DOWNGRADE`,
+ *                `LIBCOOPGAMMA_INCOMPATIBLE_UPGRADE`, or `LIBCOOPGAMMA_ERRNO_SET`
+ */
+int libcoopgamma_async_context_unmarshal(libcoopgamma_async_context_t* restrict, const void* restrict,
+					 size_t* restrict);
+
+
+/**
  * List all recognised adjustment method
  * 
  * SIGCHLD must not be ignored or blocked
@@ -1087,58 +1196,123 @@ char* libcoopgamma_get_socket_file(const char* restrict, const char* restrict);
 int libcoopgamma_connect(const char* restrict, const char* restrict, libcoopgamma_context_t* restrict);
 
 /**
- * List all available CRTC:s
+ * Send all pending outbound data
+ * 
+ * If this function or another function that sends a request
+ * to the server fails with EINTR, call this function to
+ * complete the transfer. The `async` parameter will always
+ * be in a properly configured state if a function fails
+ * with EINTR.
+ * 
+ * @param   ctx  The state of the library, must be initialised
+ * @return       Zero on success, -1 on error
+ */
+int libcoopgamma_flush(libcoopgamma_context_t* restrict);
+
+/**
+ * List all available CRTC:s, send request part
  * 
  * Cannot be used before connecting to the server
  * 
- * @param   ctx  The state of the library, must be connected
- * @return       A `NULL`-terminated list of names. You should only free
- *               the outer pointer, inner pointers are subpointers of the
- *               outer pointer and cannot be freed. `NULL` on error, in
- *               which case `ctx->error` (rather than `errno`) is read
- *               for information about the error.
+ * @param   ctx    The state of the library, must be connected
+ * @param   async  Information about the request, that is needed to
+ *                 identify and parse the response, is stored here
+ * @return         Zero on success, -1 on error
  */
-char** libcoopgamma_get_crtcs(libcoopgamma_context_t* restrict);
+int libcoopgamma_get_crtcs_send(libcoopgamma_context_t* restrict, libcoopgamma_async_context_t* restrict);
 
 /**
- * Retrieve information about a CRTC:s gamma ramps
+ * List all available CRTC:s, receive response part
  * 
- * Cannot be used before connecting to the serve
+ * @param   ctx    The state of the library, must be connected
+ * @param   async  Information about the request
+ * @return         A `NULL`-terminated list of names. You should only free
+ *                 the outer pointer, inner pointers are subpointers of the
+ *                 outer pointer and cannot be freed. `NULL` on error, in
+ *                 which case `ctx->error` (rather than `errno`) is read
+ *                 for information about the error.
+ */
+char** libcoopgamma_get_crtcs_recv(libcoopgamma_context_t* restrict, libcoopgamma_async_context_t* restrict);
+
+/**
+ * Retrieve information about a CRTC:s gamma ramps, send request part
  * 
- * @param   crtc  The name of the CRTC
- * @param   info  Output parameter for the information, must be initialised
- * @param   ctx   The state of the library, must be connected
- * @return        Zero on success, -1 on error, in which case `ctx->error`
- *                (rather than `errno`) is read for information about the error
+ * Cannot be used before connecting to the server
+ * 
+ * @param   crtc   The name of the CRTC
+ * @param   ctx    The state of the library, must be connected
+ * @param   async  Information about the request, that is needed to
+ *                 identify and parse the response, is stored here
+ * @return         Zero on success, -1 on error
+ */
+int libcoopgamma_get_gamma_info_send(const char*, libcoopgamma_context_t* restrict,
+				     libcoopgamma_async_context_t* restrict);
+
+/**
+ * Retrieve information about a CRTC:s gamma ramps, receive response part
+ * 
+ * @param   info   Output parameter for the information, must be initialised
+ * @param   ctx    The state of the library, must be connected
+ * @param   async  Information about the request
+ * @return         Zero on success, -1 on error, in which case `ctx->error`
+ *                 (rather than `errno`) is read for information about the error
  */
-int libcoopgamma_get_gamma_info(const char*, libcoopgamma_crtc_info_t* restrict,
-				libcoopgamma_context_t* restrict);
+int libcoopgamma_get_gamma_info_recv(libcoopgamma_crtc_info_t* restrict, libcoopgamma_context_t* restrict,
+				     libcoopgamma_async_context_t* restrict);
 
 /**
- * Retrieve the current gamma ramp adjustments
+ * Retrieve the current gamma ramp adjustments, send request part
  * 
- * Cannot be used before connecting to the serve
+ * Cannot be used before connecting to the server
  * 
  * @param   query  The query to send
+ * @param   ctx    The state of the library, must be connected
+ * @param   async  Information about the request, that is needed to
+ *                 identify and parse the response, is stored here
+ * @return         Zero on success, -1 on error
+ */
+int libcoopgamma_get_gamma_send(libcoopgamma_filter_query_t* restrict, libcoopgamma_context_t* restrict,
+				libcoopgamma_async_context_t* restrict);
+
+/**
+ * Retrieve the current gamma ramp adjustments, receive response part
+ * 
  * @param   table  Output for the response, must be initialised
  * @param   ctx    The state of the library, must be connected
+ * @param   async  Information about the request, that is needed to
+ *                 identify and parse the response, is stored here
  * @return         Zero on success, -1 on error, in which case `ctx->error`
  *                 (rather than `errno`) is read for information about the error
  */
-int libcoopgamma_get_gamma(libcoopgamma_filter_query_t* restrict, libcoopgamma_filter_table_t* restrict,
-			   libcoopgamma_context_t* restrict);
+int libcoopgamma_get_gamma_recv(libcoopgamma_filter_table_t* restrict, libcoopgamma_context_t* restrict,
+				libcoopgamma_async_context_t* restrict);
 
 /**
- * Apply, update, or remove a gamma ramp adjustment
+ * Apply, update, or remove a gamma ramp adjustment, send request part
+ * 
+ * Cannot be used before connecting to the server
  * 
  * @param   filter  The filter to apply, update, or remove, gamma ramp meta-data must match the CRTC's
  * @param   depth   The datatype for the stops in the gamma ramps, must match the CRTC's
  * @param   ctx     The state of the library, must be connected
- * @return          Zero on success, -1 on error, in which case `ctx->error`
- *                  (rather than `errno`) is read for information about the error
+ * @param   async   Information about the request, that is needed to
+ *                  identify and parse the response, is stored here
+ * @return          Zero on success, -1 on error
+ */
+int libcoopgamma_set_gamma_send(libcoopgamma_filter_t* restrict, libcoopgamma_depth_t,
+				libcoopgamma_context_t* restrict, libcoopgamma_async_context_t* restrict);
+
+
+/**
+ * Apply, update, or remove a gamma ramp adjustment, receive response part
+ * 
+ * @param   ctx    The state of the library, must be connected
+ * @param   async  Information about the request, that is needed to
+ *                 identify and parse the response, is stored here
+ * @return         Zero on success, -1 on error, in which case `ctx->error`
+ *                 (rather than `errno`) is read for information about the error
  */
-int libcoopgamma_set_gamma(libcoopgamma_filter_t* restrict, libcoopgamma_depth_t,
-			   libcoopgamma_context_t* restrict);
+int libcoopgamma_set_gamma_recv(libcoopgamma_context_t* restrict, libcoopgamma_async_context_t* restrict);