Add libdisfluid-gobject

1 files changed, 242 insertions, 34 deletions

diff --git a/include/disfluid/cache_entry.h b/include/disfluid/cache_entry.h
index 6004932..dddb92d 100644
--- a/include/disfluid/cache_entry.h
+++ b/include/disfluid/cache_entry.h
@@ -8,136 +8,344 @@ extern "C"
 {
 # endif				/* __cplusplus */
 
+  /**
+   * disfluid_cache_entry: (rename-to DisfluidCacheEntry):
+   *
+   * One response header, body, sprinkled with metadata.
+   */
   struct disfluid_cache_entry;
 
-  LIBDISFLUID_API LIBDISFLUID_CONST extern size_t
+  /**
+   * disfluid_cache_entry_size:
+   * @max_key: the maximum number of bytes in the key.
+   * @max_header: the maximum number of bytes in the response header.
+   * @max_body: the maximum number of bytes in the response body.
+   *
+   * Compute the required memory size to hold an entire cache entry.
+   *
+   * Returns: the minimum number of bytes to allocate.
+   */
+  DISFLUID_API DISFLUID_CONST extern size_t
     disfluid_cache_entry_size (size_t max_key,
 			       size_t max_header, size_t max_body);
 
-  LIBDISFLUID_API LIBDISFLUID_CONST extern size_t
+  /**
+   * disfluid_cache_entry_alignment:
+   *
+   * Compute the minimum alignment to hold a cache entry.
+   *
+   * Returns: the minimum alignment.
+   */
+  DISFLUID_API DISFLUID_CONST extern size_t
     disfluid_cache_entry_alignment (void);
 
-  LIBDISFLUID_API extern void
+  /**
+   * disfluid_cache_entry_init:
+   * @entry: (type DisfluidCacheEntry): an allocated memory region,
+   * with a large enough size and alignment.
+   * @max_key: the maximum number of bytes in the key.
+   * @max_header: the maximum number of bytes in the response header.
+   * @max_body: the maximum number of bytes in the response body.
+   *
+   * Prepare the cache entry.
+   */
+  DISFLUID_API extern void
     disfluid_cache_entry_init (struct disfluid_cache_entry *entry,
 			       size_t max_key,
 			       size_t max_header, size_t max_body);
 
-  LIBDISFLUID_API extern void
+  /**
+   * disfluid_cache_entry_minimum_size:
+   * @entry: (type DisfluidCacheEntry): a valid cache entry.
+   * @min_key: (out): the number of bytes in the key.
+   * @min_header: (out): the number of bytes in the response header.
+   * @min_body: (out): the number of bytes in the response body.
+   *
+   * Return the number of bytes used for the key, header and body.
+   */
+  DISFLUID_API extern void
     disfluid_cache_entry_minimum_size (const struct disfluid_cache_entry
 				       *entry, size_t *min_key,
 				       size_t *min_header, size_t *min_body);
 
-  /* -1: dest does not have enough allocated for the key, -2: for the
-     header, -3: for the key and the header, -4: for the body, -5:
-     for the key and the body, -6: for the header and the body, -7:
-     for the key, header and body. */
-  LIBDISFLUID_API extern int
+  /**
+   * disfluid_cache_entry_copy:
+   * @dest: (type DisfluidCacheEntry): an allocated cache entry.
+   * @src: (type DisfluidCacheEntry): a different allocated cache entry.
+   *
+   * Try and copy @dest to @src. It can fail if @dest is too small.
+   *
+   * Returns: 0 on success, -1 if @dest does not have enough allocated
+   * for the key, -2 for the header, -3 for the key and the header, -4
+   * for the body, -5 for the key and the body, -6 for the header and
+   * the body, -7 for the key, header and body.
+   */
+  DISFLUID_API extern int
     disfluid_cache_entry_copy (struct disfluid_cache_entry *restrict dest,
 			       const struct disfluid_cache_entry *restrict
 			       src);
 
-  LIBDISFLUID_NODISCARD LIBDISFLUID_API
+  /**
+   * disfluid_cache_entry_alloc: (constructor):
+   * @max_key: the maximum number of bytes in the key.
+   * @max_header: the maximum number of bytes in the response header.
+   * @max_body: the maximum number of bytes in the response body.
+   *
+   * Allocate a new cache entry.
+   *
+   * Returns: (nullable) (type DisfluidCacheEntry): a new cache entry.
+   */
+  DISFLUID_NODISCARD DISFLUID_API
     extern struct disfluid_cache_entry
     *disfluid_cache_entry_alloc (size_t max_key,
 				 size_t max_header, size_t max_body);
 
-  LIBDISFLUID_NODISCARD LIBDISFLUID_API
+  /**
+   * disfluid_cache_entry_dup: (constructor):
+   * @entry: (type DisfluidCacheEntry): the entry to copy.
+   *
+   * Allocate a new cache entry as a copy of @entry, keeping the same
+   * allocation limits.
+   *
+   * Returns: (nullable) (type DisfluidCacheEntry): a new cache entry.
+   */
+  DISFLUID_NODISCARD DISFLUID_API
     extern struct disfluid_cache_entry
     *disfluid_cache_entry_dup (const struct disfluid_cache_entry *entry);
 
-  LIBDISFLUID_API extern void
+  /**
+   * disfluid_cache_entry_free: (skip):
+   * @entry: (type DisfluidCacheEntry): the entry to destroy.
+   *
+   * Destroy @entry.
+   */
+  DISFLUID_API extern void
     disfluid_cache_entry_free (struct disfluid_cache_entry *entry);
 
-  LIBDISFLUID_API extern void
+  /**
+   * disfluid_cache_entry_set_request_date: (skip):
+   * @entry: (type DisfluidCacheEntry): the entry to modify.
+   * @request_date: the request date.
+   */
+  DISFLUID_API extern void
     disfluid_cache_entry_set_request_date (struct disfluid_cache_entry *entry,
 					   const struct timespec
 					   *request_date);
 
-  LIBDISFLUID_API extern void
+  /**
+   * disfluid_cache_entry_set_response_date: (skip):
+   * @entry: (type DisfluidCacheEntry): the entry to modify.
+   * @response_date: the response date.
+   */
+  DISFLUID_API extern void
     disfluid_cache_entry_set_response_date (struct disfluid_cache_entry
 					    *entry,
 					    const struct timespec
 					    *response_date);
 
-  LIBDISFLUID_API extern void
+  /**
+   * disfluid_cache_entry_set_invalidated:
+   * @entry: (type DisfluidCacheEntry): the entry to modify.
+   * @invalidated: (type boolean): whether it has been artificially invalidated.
+   */
+  DISFLUID_API extern void
     disfluid_cache_entry_set_invalidated (struct disfluid_cache_entry *entry,
 					  int invalidated);
 
-  LIBDISFLUID_API extern void
+  /**
+   * disfluid_cache_entry_invalidate:
+   * @entry: (type DisfluidCacheEntry): the entry to modify.
+   */
+  DISFLUID_API extern void
     disfluid_cache_entry_invalidate (struct disfluid_cache_entry *entry);
 
-  LIBDISFLUID_API extern int
+  /**
+   * disfluid_cache_entry_set_key:
+   * @entry: (type DisfluidCacheEntry): the entry to modify.
+   * @key: the new key bytes.
+   *
+   * Returns: 0 if the @key fits, a negative value otherwise.
+   */
+  DISFLUID_API extern int
     disfluid_cache_entry_set_key (struct disfluid_cache_entry *entry,
 				  const char *key);
 
-  LIBDISFLUID_API extern int
+  /**
+   * disfluid_cache_entry_set_response_header:
+   * @entry: (type DisfluidCacheEntry): the entry to modify.
+   * @header: the new response header bytes.
+   *
+   * Returns: 0 if the @header fits, a negative value otherwise.
+   */
+  DISFLUID_API extern int
     disfluid_cache_entry_set_response_header (struct disfluid_cache_entry
 					      *entry, const char *header);
 
-  LIBDISFLUID_API extern int
+  /**
+   * disfluid_cache_entry_set_response_body:
+   * @entry: (type DisfluidCacheEntry): the entry to modify.
+   * @body: (array length=body_length) (element-type char): the new
+   * response body bytes.
+   *
+   * Returns: 0 if the @body fits, a negative value otherwise.
+   */
+  DISFLUID_API extern int
     disfluid_cache_entry_set_response_body (struct disfluid_cache_entry
 					    *entry,
 					    size_t body_length,
 					    const char *body);
 
-  LIBDISFLUID_API extern void
+  /**
+   * disfluid_cache_entry_get_request_date: (skip):
+   * @entry: (type DisfluidCacheEntry): the entry to query.
+   * @date: the request date.
+   */
+  DISFLUID_API extern void
     disfluid_cache_entry_get_request_date (const struct disfluid_cache_entry
 					   *entry, struct timespec *date);
 
-  LIBDISFLUID_API extern void
+  /**
+   * disfluid_cache_entry_get_response_date: (skip):
+   * @entry: (type DisfluidCacheEntry): the entry to query.
+   * @date: the response date.
+   */
+  DISFLUID_API extern void
     disfluid_cache_entry_get_response_date (const struct disfluid_cache_entry
 					    *entry, struct timespec *date);
 
-  LIBDISFLUID_API LIBDISFLUID_PURE extern int
+  /**
+   * disfluid_cache_entry_is_invalidated:
+   * @entry: (type DisfluidCacheEntry): the entry to query.
+   *
+   * Returns: (type boolean): whether @entry has been artificially invalidated.
+   */
+  DISFLUID_API DISFLUID_PURE extern int
     disfluid_cache_entry_is_invalidated (const struct disfluid_cache_entry
 					 *entry);
 
-  LIBDISFLUID_API extern size_t
+  /**
+   * disfluid_cache_entry_get_key:
+   * @entry: (type DisfluidCacheEntry): the entry to query.
+   * @start: the number of bytes of the key to skip.
+   * @key: (array length=max) (element-type char): the key bytes to fill.
+   *
+   * Returns: the total number of key bytes.
+   */
+  DISFLUID_API extern size_t
     disfluid_cache_entry_get_key (const struct disfluid_cache_entry *entry,
 				  size_t start, size_t max, char *key);
 
-  LIBDISFLUID_API extern size_t
+  /**
+   * disfluid_cache_entry_get_header:
+   * @entry: (type DisfluidCacheEntry): the entry to query.
+   * @start: the number of bytes of the header to skip.
+   * @header: (array length=max) (element-type char): the header bytes to fill.
+   *
+   * Returns: the total number of response header bytes.
+   */
+  DISFLUID_API extern size_t
     disfluid_cache_entry_get_header (const struct disfluid_cache_entry *entry,
 				     size_t start, size_t max, char *header);
 
-  LIBDISFLUID_API extern size_t
+  /**
+   * disfluid_cache_entry_get_body:
+   * @entry: (type DisfluidCacheEntry): the entry to query.
+   * @start: the number of bytes of the body to skip.
+   * @body: (array length=max) (element-type char): the body bytes to fill.
+   *
+   * Returns: the total number of response body bytes.
+   */
+  DISFLUID_API extern size_t
     disfluid_cache_entry_get_body (const struct disfluid_cache_entry *entry,
 				   size_t start, size_t max, char *body);
 
-  LIBDISFLUID_NODISCARD LIBDISFLUID_API extern int
+  /**
+   * disfluid_cache_entry_load: (skip):
+   * @entry: (type DisfluidCacheEntry): the entry to initialize.
+   * @load_key: (type boolean): whether to actually load the key.
+   * @load_header: (type boolean): whether to actually load the response header.
+   * @load_body: (type boolean): whether to actually load the response body.
+   * @read_impl: how to read data.
+   * @skip: how to skip data.
+   *
+   * Returns: 0 on success, or a negative error code.
+   */
+  DISFLUID_NODISCARD DISFLUID_API extern int
     disfluid_cache_entry_load (struct disfluid_cache_entry *entry,
 			       int load_key,
 			       int load_header,
 			       int load_body,
-			       ssize_t (*read_impl) (void *context,
+			       ssize_t (*read_impl) (void *user_data,
 						     void *buffer,
 						     size_t max_size),
 			       int (*skip) (void *context, size_t size),
 			       void *context);
 
-  LIBDISFLUID_NODISCARD LIBDISFLUID_FD_ARG_READ_2 LIBDISFLUID_API
+  /**
+   * disfluid_cache_entry_read:
+   * @entry: (type DisfluidCacheEntry): the entry to initialize.
+   * @load_key: (type boolean): whether to actually load the key.
+   * @load_header: (type boolean): whether to actually load the response header.
+   * @load_body: (type boolean): whether to actually load the response body.
+   * @fd: the file descriptor to use.
+   *
+   * Returns: 0 on success, or a negative error code.
+   */
+  DISFLUID_NODISCARD DISFLUID_FD_ARG_READ_2 DISFLUID_API
     extern int disfluid_cache_entry_read (struct disfluid_cache_entry *entry,
 					  int load_key,
 					  int load_header,
 					  int load_body, int fd);
 
-  LIBDISFLUID_NODISCARD LIBDISFLUID_API extern int
+  /**
+   * disfluid_cache_entry_fread: (skip):
+   * @entry: (type DisfluidCacheEntry): the entry to initialize.
+   * @load_key: (type boolean): whether to actually load the key.
+   * @load_header: (type boolean): whether to actually load the response header.
+   * @load_body: (type boolean): whether to actually load the response body.
+   * @f: the file handle to use.
+   *
+   * Returns: 0 on success, or a negative error code.
+   */
+  DISFLUID_NODISCARD DISFLUID_API extern int
     disfluid_cache_entry_fread (struct disfluid_cache_entry *entry,
 				int load_key,
 				int load_header, int load_body, FILE * f);
 
-  LIBDISFLUID_NODISCARD LIBDISFLUID_API extern int
+  /**
+   * disfluid_cache_entry_save:
+   * @entry: (type DisfluidCacheEntry): the entry to save.
+   * @write_impl: how to write data.
+   * @user_context: (closure write_impl): the closure data for the callback.
+   *
+   * Returns: 0 on success, or a negative error code.
+   */
+  DISFLUID_NODISCARD DISFLUID_API extern int
     disfluid_cache_entry_save (const struct disfluid_cache_entry *entry,
 			       ssize_t (*write_impl) (void *context,
 						      const void *buffer,
 						      size_t max_size),
-			       void *context);
-
-  LIBDISFLUID_NODISCARD LIBDISFLUID_FD_ARG_WRITE_2 LIBDISFLUID_API
+			       void *user_context);
+
+  /**
+   * disfluid_cache_entry_write:
+   * @entry: (type DisfluidCacheEntry): the entry to save.
+   * @fd: the file descriptor to use.
+   *
+   * Returns: 0 on success, or a negative error code.
+   */
+  DISFLUID_NODISCARD DISFLUID_FD_ARG_WRITE_2 DISFLUID_API
     extern int disfluid_cache_entry_write (const struct disfluid_cache_entry
 					   *entry, int fd);
 
-  LIBDISFLUID_NODISCARD LIBDISFLUID_API extern int
+  /**
+   * disfluid_cache_entry_fwrite:
+   * @entry: (type DisfluidCacheEntry): the entry to save.
+   * @f: the file handle to use.
+   *
+   * Returns: 0 on success, or a negative error code.
+   */
+  DISFLUID_NODISCARD DISFLUID_API extern int
     disfluid_cache_entry_fwrite (const struct disfluid_cache_entry *entry,
 				 FILE * f);