From de68b48a1ff110e965f2c02fc930201ece9980d2 Mon Sep 17 00:00:00 2001
From: Timo Dritschler <timo.dritschler@kit.edu>
Date: Fri, 10 Apr 2015 19:01:29 +0200
Subject: Made all in-source documentation Gtk-Doc conformant
---
src/kiro-client.c | 9 ----
src/kiro-client.h | 84 ++++++++++++++++++------------------
src/kiro-rdma.h | 31 +++++++++++++-
src/kiro-sb.c | 11 -----
src/kiro-sb.h | 125 ++++++++++++++++++++++++++++--------------------------
src/kiro-server.c | 9 ----
src/kiro-server.h | 40 +++++++----------
src/kiro-trb.c | 11 -----
src/kiro-trb.h | 115 +++++++++++++++++++++++--------------------------
9 files changed, 207 insertions(+), 228 deletions(-)
diff --git a/src/kiro-client.c b/src/kiro-client.c
index 01f4fb0..b0f5d45 100644
--- a/src/kiro-client.c
+++ b/src/kiro-client.c
@@ -16,15 +16,6 @@
Franklin St, Fifth Floor, Boston, MA 02110, USA
*/
-/**
- * SECTION: kiro-client
- * @Short_description: KIRO RDMA Client / Consumer
- * @Title: KiroClient
- *
- * KiroClient implements the client / active / consumer side of the the RDMA
- * Communication Channel. It uses a KIRO-CLIENT to manage data read from the Server.
- */
-
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
diff --git a/src/kiro-client.h b/src/kiro-client.h
index 1941c7a..ff6c00f 100644
--- a/src/kiro-client.h
+++ b/src/kiro-client.h
@@ -54,13 +54,6 @@ struct _KiroClient {
KiroClientPrivate *priv;
};
-
-/**
- * IbvConnectorInterface:
- *
- * Base interface for IbvConnectors.
- */
-
struct _KiroClientClass {
GObjectClass parent_class;
@@ -70,28 +63,26 @@ struct _KiroClientClass {
/* GObject and GType functions */
-/**
- * kiro_client_get_type: (skip)
- * Returns: GType of #KiroClient
- */
GType kiro_client_get_type (void);
/**
- * kiro_client_new - Creates a new #KiroClient
+ * kiro_client_new:
+ *
+ * Creates a new, unconnected #KiroClient and returns a pointer to it.
+ *
* Returns: (transfer full): A pointer to a new #KiroClient
- * Description:
- * Creates a new, unconnected #KiroClient and returns a pointer to it.
* See also:
* kiro_client_free, kiro_client_connect
*/
KiroClient* kiro_client_new (void);
/**
- * kiro_client_free - 'Destroys' the given #KiroClient
+ * kiro_client_free:
* @client: (transfer none): The #KiroClient that is to be freed
- * Description:
+ *
* Transitions the #KiroServer through all necessary shutdown routines and
* frees the object memory.
+ *
* Note:
* The memory content that has been transfered from the server is
* automatically freed when calling this function. If you want to continue
@@ -107,15 +98,17 @@ void kiro_client_free (KiroClient *client);
/* client functions */
/**
- * kiro_client_connect - Connect a #KiroClient to a Server
+ * kiro_client_connect:
* @client: (transfer none): The #KiroClient to connect
* @dest_addr: (transfer none): The address of the target server
* @dest_port: (transfer none): The port of the target server
- * Returns:
- * 0 if the connection was successful, -1 in case of connection error
- * Description:
+ *
* Connects the given #KiroClient to a KIRO server described by @dest_addr and
* @dest_port.
+ *
+ * Returns:
+ * 0 if the connection was successful, -1 in case of connection error
+ *
* Note:
* When building a connection to the server, memory for the transmission is
* created as well.
@@ -125,11 +118,12 @@ void kiro_client_free (KiroClient *client);
int kiro_client_connect (KiroClient *client, const char *dest_addr, const char *dest_port);
/**
- * kiro_client_disconnect - Diconnect a #KiroClient from the Server
+ * kiro_client_disconnect:
* @client: (transfer none): The #KiroClient to disconnect
- * Description:
+ *
* Disconnects the given #KiroClient from the KIRO server that it is connected
* to. If the @client is not connected, this function has no effect.
+ *
* Note:
* The memory content that has been transfered from the server is
* automatically freed when calling this function. If you want to continue
@@ -142,14 +136,15 @@ int kiro_client_connect (KiroClient *client, const char *des
void kiro_client_disconnect (KiroClient *client);
/**
- * kiro_client_sync - Read data from the connected server
+ * kiro_client_sync:
* @client: (transfer none): The #KiroServer to use sync on
- * Returns:
- * 0 if successful, -1 in case of synchronisation error
- * Description:
+ *
* This synchronizes the client with the server, clining the memory
* provided by the server to the local client. The memory can be accessed by
* using kiro_client_get_memory().
+ *
+ * Returns:
+ * 0 if successful, -1 in case of synchronisation error
* Note:
* The server can send a 'reallocation' request to the client, forcing it to
* reallocate new memory freeing the old memory in the process. This might
@@ -160,19 +155,20 @@ void kiro_client_disconnect (KiroClient *client);
int kiro_client_sync (KiroClient *client);
/**
- * kiro_client_sync_partial - Read data from the connected server
+ * kiro_client_sync_partial:
* @client: (transfer none): The #KiroServer to use sync on
* @remote_offset: remote read offset in bytes
* @size: ammount of bytes to read. 0 for 'until end'
* @local_offset: offset for the storage in the local buffer
- * Returns:
- * 0 if successful, -1 in case of synchronisation error
- * Description:
+ *
* This synchronizes the client with the server, clining the memory
* provided by the server to the local client. The memory can be accessed by
* using kiro_client_get_memory(). Uses the offset parameters to determine
* which memory region to read from the server and where to store the
* information to.
+ *
+ * Returns:
+ * 0 if successful, -1 in case of synchronisation error
* Note:
* The server can send a 'reallocation' request to the client, forcing it to
* reallocate new memory freeing the old memory in the process. This might
@@ -183,23 +179,26 @@ int kiro_client_sync (KiroClient *client);
int kiro_client_sync_partial (KiroClient *client, gulong remote_offset, gulong size, gulong local_offset);
/**
- * kiro_client_ping_server - Sends a PING to the server
+ * kiro_client_ping_server:
* @client: (transfer none): The #KiroServer to send the PING from
- * Returns:
- * A #guint telling the time (in microseconds) how long it took for the
- * connected #KiroServer to reply
- * Description:
+ *
* Sends a PING package to the connected #KiroServer and waits for a PONG
* package from that server. The time between sending the PING and receiving
* the PONG (in microseconds) is measured and returned by this function.
+ *
+ * Returns:
+ * A #guint telling the time (in microseconds) how long it took for the
+ * connected #KiroServer to reply
*/
gint kiro_client_ping_server (KiroClient *client);
/**
- * kiro_client_get_memory - Return a pointer to the current client memory
+ * kiro_client_get_memory:
* @client: (transfer none): The #KiroClient to get the memory from
- * Returns: (transfer none):
- * A pointer to the current memory of the client.
+ *
+ * Provides a pointer to the content of the internal memory that was pulled
+ * from the server.
+ *
* Note:
* The server can instruct the client to reallocate memory on the next
* occurrence of kiro_client_sync(), freeing the old memory. Also, calling
@@ -209,18 +208,21 @@ gint kiro_client_ping_server (KiroClient *client);
* information from kiro_client_get_memory() and
* kiro_client_get_memory_size() first.
* The returned memory might under NO circumstances be freed by the user!
+ * Returns: (transfer none):
+ * A pointer to the current memory of the client.
* See also:
* kiro_client_get_memory_size, kiro_client_sync
*/
void* kiro_client_get_memory (KiroClient *client);
/**
- * kiro_client_get_memory_size - Return the client memory size in bytes
+ * kiro_client_get_memory_size:
* @client: (transfer none): The #KiroClient to get the memory size of
+ *
+ * Returns the size of the allocated memory of @client, in bytes.
+ *
* Returns:
* The size of the given #KiroClient memory in bytes
- * Description:
- * Returns the size of the allocated memory of @client, in bytes.
* Note:
* The server can instruct the client to reallocate memroy on the next
* occurrence of kiro_server_sync(), freeing the old memory. This might also
diff --git a/src/kiro-rdma.h b/src/kiro-rdma.h
index c17e044..cd07f84 100644
--- a/src/kiro-rdma.h
+++ b/src/kiro-rdma.h
@@ -16,6 +16,13 @@
Franklin St, Fifth Floor, Boston, MA 02110, USA
*/
+/**
+ * SECTION: kiro-rdma
+ *
+ * KIRO toolbox for common operations with and around the
+ * RDMA Connection Manager for InfiniBand mechanisms
+ */
+
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
@@ -26,7 +33,14 @@
#include <rdma/rdma_cma.h>
-
+/**
+ * kiro_connection_context: (skip)
+ *
+ * Holds all necessary metainformation to indentify with an abstract Kiro
+ * Connection. This is constructed and attached to a rdma_cm_id's context
+ * pointer.
+ *
+ */
struct kiro_connection_context {
// Information and necessary structurs
@@ -48,7 +62,13 @@ struct kiro_connection_context {
};
-
+/**
+ * kiro_ctrl_msg: (skip)
+ *
+ * Struct representing a Kiro control-flow message which is used internally by
+ * all kiro komponents to communicate with their peer(s)
+ *
+ */
struct kiro_ctrl_msg {
enum {
@@ -64,6 +84,13 @@ struct kiro_ctrl_msg {
};
+/**
+ * kiro_rdma_mem: (skip)
+ *
+ * Container for all necessary information and data-elements that are needed to
+ * describe memory that can be managed by means of RDMA
+ *
+ */
struct kiro_rdma_mem {
void *mem; // Pointer to the beginning of the memory block
diff --git a/src/kiro-sb.c b/src/kiro-sb.c
index f6e9e6f..e5a6769 100644
--- a/src/kiro-sb.c
+++ b/src/kiro-sb.c
@@ -16,18 +16,7 @@
Franklin St, Fifth Floor, Boston, MA 02110, USA
*/
-/**
- * SECTION: kiro-sb
- * @Short_description: KIRO 'Synchronizing Buffer'
- * @Title: KiroSb
- *
- * KiroSb implements a 'Synchronizing Buffer' that automatically keeps the local
- * memory content up to date by mirroring the remote SyncBuffers memory content
- * automatically without any required user interaction
- */
-
#include <stdio.h>
-
#include <stdlib.h>
#include <string.h>
#include <glib.h>
diff --git a/src/kiro-sb.h b/src/kiro-sb.h
index 319d6f0..0f155c3 100644
--- a/src/kiro-sb.h
+++ b/src/kiro-sb.h
@@ -53,13 +53,6 @@ struct _KiroSb {
};
-
-/**
- * IbvConnectorInterface:
- *
- * Base interface for IbvConnectors.
- */
-
struct _KiroSbClass {
GObjectClass parent_class;
@@ -68,27 +61,25 @@ struct _KiroSbClass {
/* GObject and GType functions */
-/**
- * kiro_sb_get_type: (skip)
- * Returns: GType of #KiroSb
- */
GType kiro_sb_get_type (void);
/**
- * kiro_sb_new - Creates a new #KiroSb
- * Returns: (transfer full): A pointer to a new #KiroSb
- * Description:
+ * kiro_sb_new:
+ *
* Creates a new #KiroSb and returns a pointer to it.
+ *
+ * Returns: (transfer full): A pointer to a new #KiroSb
* See also:
* kiro_sb_free
*/
KiroSb* kiro_sb_new (void);
/**
- * kiro_sb_free - 'Destroys' the given #KiroSb
- * @trb: (transfer none): The #KiroSb that is to be freed
- * Description:
- * Clears all underlying memory and frees the object memory.
+ * kiro_sb_free:
+ * @sb: (transfer none): The #KiroSb that is to be freed
+ *
+ * Clears all underlying memory and frees the object memory.
+ *
* Note:
* The internal memory is also freed when calling this function. If you want
* to continue using the raw @sb memory after you call this function, you need
@@ -100,11 +91,12 @@ KiroSb* kiro_sb_new (void);
void kiro_sb_free (KiroSb *sb);
/**
- * kiro_sb_stop - Stops the #KiroSb and clears all internal memory
+ * kiro_sb_stop:
* @sb: (transfer none): The #KiroSb to stop
- * Description:
+ *
* The given #KiroSb is stopped and all internal memory is cleared. It is put
* back into its initial state and it can be used as if it was just created
+ *
* See also:
* kiro_sb_new, kiro_sb_serve, kiro_sb_clone
*/
@@ -116,13 +108,14 @@ typedef gboolean KiroContinueFlag;
#define KIRO_CALLBACK_REMOVE FALSE
/**
- * KiroSbSyncCallbackFunc - Function type for sync callbacks os a #KiroSb
+ * KiroSbSyncCallbackFunc:
* @user_data: (transfer none): The #user_data which was provided during
* registration of this callback
- * Returns: A #KiroContinueFlag
- * Description:
+ *
* Defines the type of a callback function which will be invoked every time
* the #KiroSb syncs new data
+ *
+ * Returns: A #KiroContinueFlag deciding whether to keep this callback alive or not
* Note:
* Returning %FALSE or %KIRO_CALLBACK_REMOVE will automatically remove the callback
* from the internal callback list. Return %TRUE or %KIRO_CALLBACK_CONTINUE if you
@@ -133,13 +126,14 @@ typedef gboolean KiroContinueFlag;
typedef KiroContinueFlag (*KiroSbSyncCallbackFunc) (void *user_data);
/**
- * kiro_sb_add_sync_callback - Add a sync callback to the #KiroSb
- * @sb: (tranfer none): The #KiroSb to register this callback to
- * @func: (transfer none): A function pointer to the callback function
- * Returns: The internal id of the registerd callback
- * Description:
+ * kiro_sb_add_sync_callback:
+ * @sb: (transfer none): The #KiroSb to register this callback to
+ * @callback: (transfer none) (scope call): A function pointer to the callback function
+ *
* Adds a callback to the passed #KiroSbSyncCallbackFunc to this #KiroSb which
* will be invoked every time the #KiroSb syncs new data.
+ *
+ * Returns: The internal id of the registerd callback
* Note:
* The sync callbacks will only be invoked on a 'clonig' #KiroSb. All
* registered callbacks will be invoked in the order they were added to the
@@ -150,16 +144,17 @@ typedef KiroContinueFlag (*KiroSbSyncCallbackFunc) (void *user_data);
gulong kiro_sb_add_sync_callback (KiroSb *sb, KiroSbSyncCallbackFunc callback, void *user_data);
/**
- * kiro_sb_remove_sync_callback - Remove a callback from the list
+ * kiro_sb_remove_sync_callback:
* @sb: (transfer none): The #KiroSb to remove the callback from
* @id: The id of the callback to be removed
- * Returns: A #gboolean. %TRUE if the callback was found and removed. %FALSE
- * otherwise
- * Description:
+ *
* Removes the callback with the given @id from the internal list. If the
* callback with the given @id was not found %FALSE is returned. If the
* callback with the given @id was found, it will be removed from the callback
* list and %TRUE is returned
+ *
+ * Returns: A #gboolean. %TRUE if the callback was found and removed. %FALSE
+ * otherwise
* Note:
* Any currently active callback will still finish before it is removed from
* the list.
@@ -169,10 +164,11 @@ gulong kiro_sb_add_sync_callback (KiroSb *sb, KiroSbSyncCallbackFunc callback
gboolean kiro_sb_remove_sync_callback (KiroSb *sb, gulong id);
/**
- * kiro_sb_clear_sync_callbacks - Clear all sync callbacks
+ * kiro_sb_clear_sync_callbacks:
* @sb: (transfer none): The #KiroSb to perform this operation on
- * Description:
+ *
* Removes all registerd callbacks from the internal list
+ *
* Note:
* Any currently active callbacks will still finish before they are removed
* from the list
@@ -182,14 +178,13 @@ gboolean kiro_sb_remove_sync_callback (KiroSb *sb, gulong id);
void kiro_sb_clear_sync_callbacks (KiroSb *sb);
/**
- * kiro_sb_serve - Allow remote KiroSbs to clone this buffers memory
- * Returns: A gboolean. TRUE = success. FALSE = fail.
+ * kiro_sb_serve:
* @sb: (transfer none): The #KiroSb to perform this operation on
* @size: Size in bytes of the content that will be served
* @addr: Optional address parameter to define where to listen for new
* connections.
* @port: Optional port to listen on for new connections
- * Description:
+ *
* Allows other remote #KiroSbs to connect to this #KiroSb and clone its
* memory. The internal memory is initially empty. Use the kiro_sb_push or
* kiro_sb_push_dma functions to update the served data.
@@ -198,6 +193,8 @@ void kiro_sb_clear_sync_callbacks (KiroSb *sb);
* the first device it can find. If @port is given, the #KiroSb will listen
* for new connections on this specific port. Otherwise, the default port
* '60010' will be used.
+ *
+ * Returns: A gboolean. TRUE = success. FALSE = fail.
* Note:
* A #KiroSb that already 'serves' its content can no longer clone
* other remote #KiroSbs.
@@ -207,14 +204,15 @@ void kiro_sb_clear_sync_callbacks (KiroSb *sb);
gboolean kiro_sb_serve (KiroSb *sb, gulong size, const gchar *addr, const gchar *port);
/**
- * kiro_sb_clone - Clone the content of a remote #KiroSb
- * Returns: A gboolean. TRUE = connection successful. FALSE = connection failed.
+ * kiro_sb_clone:
* @sb: (transfer none): The #KiroSb to perform this operation on
* @address: The InfiniBand address of the remote #KiroSb which should be cloned
* @port: The InfiniBand port of the remote #KiroSb which should be cloned
- * Description:
+ *
* Connects to the remote #KiroSb given by @address and @port and
* continuousely clones its content into the local #KiroSb
+ *
+ * Returns: A gboolean. TRUE = connection successful. FALSE = connection failed.
* Note:
* A #KiroSb that clones a remote #KiroSb can no longer start to 'serve' its
* content to other remote #KiroSbs
@@ -224,12 +222,13 @@ gboolean kiro_sb_serve (KiroSb *sb, gulong size, const gchar *addr,
gboolean kiro_sb_clone (KiroSb *sb, const gchar *address, const gchar *port);
/**
- * kiro_sb_get_size - Get the size in bytes of the managed memory
- * Returns: A gulong giving the size of the managed memory in bytes
+ * kiro_sb_get_size:
* @sb: (transfer none): The #KiroSb to perform this operation on
- * Description:
+ *
* Returns the size in bytes of the content that is being served and/or cloned
* from.
+ *
+ * Returns: A gulong giving the size of the managed memory in bytes
* Note:
* Since #KiroSb uses an internal triple buffer, the value gained from this
* function only gives the size of one element from that buffer. The size of
@@ -240,33 +239,36 @@ gboolean kiro_sb_clone (KiroSb *sb, const gchar *address, const gchar *
gulong kiro_sb_get_size (KiroSb *sb);
/**
- * kiro_sb_freeze - Stop auto syncing
+ * kiro_sb_freeze:
* @sb: (transfer none): The #KiroSb to perform this operation on
- * Description:
+ *
* Stops the given #KiroSb from automatically syncing.
+ *
* See also:
* kiro_sb_thaw
*/
void kiro_sb_freeze (KiroSb *sb);
/**
- * kiro_sb_thaw - Enable auto syncing
+ * kiro_sb_thaw:
* @sb: (transfer none): The #KiroSb to perform this operation on
- * Description:
+ *
* Enable the given #KiroSb automatic syncing.
+ *
* See also:
* kiro_sb_freeze
*/
void kiro_sb_thaw (KiroSb *sb);
/**
- * kiro_sb_get_data - Get a pointer to the stored data
+ * kiro_sb_get_data:
* @sb: (transfer none) The #KiroSb to get the data from
- * Returns: A void pointer the stored data
- * Description:
+ *
* Returns a void pointer to the most current incarnation of the stored data.
* Data might either change by pushing (in case of a 'serving' #KiroSb) or
* after (automatic or manual) syncing (in case of a 'cloning' #KiroSb).
+ *
+ * Returns: (transfer none): A void pointer the stored data
* Note:
* The returned pointer to the element might become invalid at any time by
* automatic or manual sync. Under no circumstances might the returned pointer
@@ -279,12 +281,13 @@ void kiro_sb_thaw (KiroSb *sb);
void* kiro_sb_get_data (KiroSb *sb);
/**
- * kiro_sb_get_data_blocking - Wait for new data and return a pointer to it
+ * kiro_sb_get_data_blocking:
* @sb: (transfer none) The #KiroSb to get the data from
- * Returns: A void pointer the stored data
- * Description:
+ *
* Calling this function will do the same thing as kiro_sb_get_data, but it
* will internaly wait until new data has arived before returning it.
+ *
+ * Returns: (transfer none): A void pointer the stored data
* Note:
* The returned pointer to the element might become invalid at any time by
* automatic or manual sync. Under no circumstances might the returned pointer
@@ -297,30 +300,32 @@ void* kiro_sb_get_data (KiroSb *sb);
void* kiro_sb_get_data_blocking (KiroSb *sb);
/**
- * kiro_sb_push - Push data into the memory
+ * kiro_sb_push:
* @sb: (transfer none) The #KiroSb to get the data from
* @data: (transfer none) void pointer to copy data from
- * Returns: %TRUE on success %FALSE in case of error
- * Desciption:
+ *
* Updates the internal memory by memcopy()-ing the given element into it.
* This operation is only valid for 'serving' #KiroSb. Calling this function
* on a 'cloning' #KiroSb will allways return %FALSE.
+ *
+ * Returns: %TRUE on success %FALSE in case of error
* Note:
* The internal memcopy() will assume an element of the correct size (given
- * with the initial call to kiro_sb_serve or returned by kiro_sb_get_size)
+ * with the initial call to kiro_sb_serve or returned by kiro_sb_get_size)
* See also:
* kiro_sb_get_size, kiro_sb_serve
*/
gboolean kiro_sb_push (KiroSb *sb, void *data);
/**
- * kiro_sb_push_dma - Push data into the memory using memory access
+ * kiro_sb_push_dma:
* @sb: (transfer none) The #KiroSb to get the data from
- * Returns: A pointer to the memory where the new data should be stored
- * Desciption:
+ *
* Returns a pointer where the new data should be stored.
* This operation is only valid for a 'serving' #KiroSb. Calling this
* function on a 'cloning' #KiroSb will allways return a %NULL pointer.
+ *
+ * Returns: (transfer none): A pointer to the memory where the new data should be stored
* Note:
* It is the users responsibility to ensure no more data is written to the
* pointed memory then was specified with the initial call to kiro_sb_serve or
diff --git a/src/kiro-server.c b/src/kiro-server.c
index f8dd9d3..041814d 100644
--- a/src/kiro-server.c
+++ b/src/kiro-server.c
@@ -16,15 +16,6 @@
Franklin St, Fifth Floor, Boston, MA 02110, USA
*/
-/**
- * SECTION: kiro-server
- * @Short_description: KIRO RDMA Server / Consumer
- * @Title: KiroServer
- *
- * KiroServer implements the server / passive / provider side of the the RDMA
- * Communication Channel. It uses a KIRO-TRB to manage its data.
- */
-
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
diff --git a/src/kiro-server.h b/src/kiro-server.h
index 655140a..8479e15 100644
--- a/src/kiro-server.h
+++ b/src/kiro-server.h
@@ -54,13 +54,6 @@ struct _KiroServer {
KiroServerPrivate *priv;
};
-
-/**
- * IbvConnectorInterface:
- *
- * Base interface for IbvConnectors.
- */
-
struct _KiroServerClass {
GObjectClass parent_class;
@@ -70,29 +63,26 @@ struct _KiroServerClass {
/* GObject and GType functions */
-
-/**
- * kiro_server_get_type: (skip)
- * Returns: GType of KiroServer
- */
GType kiro_server_get_type (void);
/**
- * kiro_server_new - Creates a new #KiroServer
+ * kiro_server_new:
+ * Creates a new, unbound #KiroServer and returns a pointer to it.
+ *
* Returns: (transfer full): A pointer to a new #KiroServer
- * Description:
- * Creates a new, unbound #KiroServer and returns a pointer to it.
+ *
* See also:
* kiro_server_start, kiro_server_free
*/
KiroServer* kiro_server_new (void);
/**
- * kiro_server_free - 'Destroys' the given #KiroServer
+ * kiro_server_free:
* @server: The #KiroServer that is to be freed
- * Description:
+ *
* Transitions the #KiroServer through all necessary shutdown routines and
* frees the object memory.
+ *
* Note:
* The memory that is given to the server when calling kiro_server_start will
* NOT be freed! The user is responsible to free this memory, if no longer
@@ -106,15 +96,16 @@ void kiro_server_free (KiroServer *server);
/* server functions */
/**
- * kiro_server_start - Starts the server, providing the given memory
+ * kiro_server_start:
* @server: #KiroServer to perform the operation on
* @bind_addr: Local address to bind the server to
* @bind_port: Local port to listen for connections
* @mem: (transfer none): Pointer to the memory that is to be provided
* @mem_size: Size in bytes of the given memory
- * Description:
+ *
* Starts the #KiroServer to provide the given memory to any connecting
* client.
+ *
* Notes:
* If the bind_addr is NULL, the server will bind to the first device
* it can find on the machine and listen across all IPs. Otherwise it
@@ -131,22 +122,23 @@ int kiro_server_start (KiroServer *server, const char *bind_addr, const char *bi
/**
- * kiro_server_realloc - Change the memory that is provided by the server
+ * kiro_server_realloc:
* @server: #KiroServer to perform the operation on
* @mem: (transfer none): Pointer to the memory that is to be provided
* @mem_size: Size in bytes of the given memory
- * Description:
+ *
* Changes the memory that is provided by the server. All connected clients
* will automatically be informed about this change.
*/
-void kiro_server_realloc (KiroServer *self, void* mem, size_t mem_size);
+void kiro_server_realloc (KiroServer *server, void* mem, size_t mem_size);
/**
- * kiro_server_stop - Stops the server
+ * kiro_server_stop:
* @server: #KiroServer to perform the operation on
- * Description:
+ *
* Stops the given #KiroServer
+ *
* See also:
* kiro_server_start
*/
diff --git a/src/kiro-trb.c b/src/kiro-trb.c
index c3ed968..97ca047 100644
--- a/src/kiro-trb.c
+++ b/src/kiro-trb.c
@@ -16,18 +16,7 @@
Franklin St, Fifth Floor, Boston, MA 02110, USA
*/
-/**
- * SECTION: kiro-trb
- * @Short_description: KIRO 'Transmittable Ring Buffer'
- * @Title: KiroTrb
- *
- * KiroTrb implements a 'Transmittable Ring Buffer' that holds all necessary information
- * about its content inside itself, so its data can be exchanged between different
- * instances of the KiroTrb Class and/or sent over a network.
- */
-
#include <stdio.h>
-
#include <stdlib.h>
#include <string.h>
#include <glib.h>
diff --git a/src/kiro-trb.h b/src/kiro-trb.h
index bec8626..3549a1d 100644
--- a/src/kiro-trb.h
+++ b/src/kiro-trb.h
@@ -53,13 +53,6 @@ struct _KiroTrb {
};
-
-/**
- * IbvConnectorInterface:
- *
- * Base interface for IbvConnectors.
- */
-
struct _KiroTrbClass {
GObjectClass parent_class;
@@ -78,32 +71,30 @@ struct KiroTrbInfo {
/* GObject and GType functions */
-/**
- * kiro_trb_get_type: (skip)
- * Returns: GType of #KiroTrb
- */
GType kiro_trb_get_type (void);
/**
- * kiro_trb_new - Creates a new #KiroTrb
- * Returns: (transfer full): A pointer to a new #KiroTrb
- * Description:
+ * kiro_trb_new:
+ *
* Creates a new, unshaped #KiroTrb and returns a pointer to it.
+ *
+ * Returns: (transfer full): A pointer to a new #KiroTrb
* See also:
* kiro_trb_free, kiro_trb_reshape
*/
KiroTrb* kiro_trb_new (void);
/**
- * kiro_trb_free - 'Destroys' the given #KiroTrb
+ * kiro_trb_free:
* @trb: (transfer none): The #KiroTrb that is to be freed
- * Description:
- * Clears all underlying memory and frees the object memory.
+ *
+ * Clears all underlying memory and frees the object memory.
+ *
* Note:
* The internal memory is also freed when calling this function. If you want
* to continue using the raw @trb memory after call this function, you need to
* memcpy() its content using the information optained from
- * kiro_trb_get_raw_buffer and kiro_trb_get_raw_size.
+ * kiro_trb_get_raw_buffer and kiro_trb_get_raw_size.
* See also:
* kiro_trb_new
*/
@@ -114,10 +105,10 @@ void kiro_trb_free (KiroTrb *trb);
/**
* kiro_trb_get_element_size:
- * Returns the element size in bytes
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
* Returns the size of the individual elements in the buffer
+ *
* See also:
* kiro_trb_reshape, kiro_trb_adopt, kiro_trb_clone
*/
@@ -125,11 +116,11 @@ uint64_t kiro_trb_get_element_size (KiroTrb *trb);
/**
* kiro_trb_get_max_elements:
- * Returns the capacity of the buffer
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
* Returns the mximal number of elements that can be stored in
* the buffer
+ *
* See also:
* kiro_trb_get_element_size, kiro_trb_reshape, kiro_trb_adopt,
* kiro_trb_clone
@@ -139,10 +130,10 @@ uint64_t kiro_trb_get_max_elements (KiroTrb *trb);
/**
* kiro_trb_get_raw_size:
- * Returns the size of the buffer memory
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
* Returns the size of the buffers internal memory
+ *
* Notes:
* The returned size is given INCLUDING the header on top of the
* buffers internal memory
@@ -155,9 +146,10 @@ uint64_t kiro_trb_get_raw_size (KiroTrb *trb);
/**
* kiro_trb_get_raw_buffer:
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
* Returns a pointer to the memory structure of the given buffer.
+ *
* Returns: (transfer none): a pointer to the buffer memory
* Notes:
* The returned pointer points to the beginning of the internal
@@ -180,10 +172,11 @@ void* kiro_trb_get_raw_buffer (KiroTrb *trb);
/**
* kiro_trb_get_element:
- * @trb: #KiroTrb to perform the operation on
+ * @trb: (transfer none): #KiroTrb to perform the operation on
* @index: Index of the element in the buffer to access
- * Description:
+ *
* Returns a pointer to the element in the buffer at the given index.
+ *
* Returns: (transfer none): a pointer to the element at the given index.
* Notes:
* The returned pointer to the element is only guaranteed to be valid
@@ -204,12 +197,12 @@ void* kiro_trb_get_element (KiroTrb *trb, glong index);
/**
* kiro_trb_dma_push:
- * Gives DMA to the next element and pushes the buffer
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
* Returns a pointer to the next element in the buffer and increases
* all internal counters and meta data as if an element was pushed
* onto the buffer.
+ *
* Returns: (transfer none): Pointer to the bginning of element memory
* Notes:
* The returned pointer to the element is only guaranteed to be valid
@@ -230,10 +223,10 @@ void* kiro_trb_dma_push (KiroTrb *trb);
/**
* kiro_trb_flush:
- * Flushes the buffer
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
* Flushes the internal buffer so the buffer is 'empty' again.
+ *
* Notes:
* The underlying memory is not cleared, freed or rewritten.
* Only the header is rewritten and the internal pointer and
@@ -247,12 +240,12 @@ void kiro_trb_flush (KiroTrb *trb);
/**
* kiro_trb_purge:
* Completely resets the Buffer
- * @trb: #KiroTrb to perform the operation on
- * @free_memory: True = internal memory will be free()'d,
- * False = internal memory will be 'orphaned'
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ * @free_memory: Decides how to treat intermal memory on purge
+ *
* Resets all internal structures so the TRB becomes
* 'uninitialized' again.
+ *
* Notes:
* Depending on the 'free_memory' argument, any currently
* held internal memory either gets free()'d or is simply
@@ -265,11 +258,11 @@ void kiro_trb_purge (KiroTrb *trb, gboolean free_memory);
/**
* kiro_trb_is_setup:
- * Returns the setup status of the buffer
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
* Returns an integer designating of the buffer is ready to
* be used or needs to be 'reshaped' before it can accept data
+ *
* Notes:
* A return value of 0 designates that the buffer is not ready
* to be used. Values greater than 0 designate that the buffer
@@ -282,15 +275,15 @@ int kiro_trb_is_setup (KiroTrb *trb);
/**
* kiro_trb_reshape:
- * Reallocates internal memory and structures
- * @trb: #KiroTrb to perform the operation on
+ * @trb: (transfer none): #KiroTrb to perform the operation on
* @element_size: Individual size of the elements to store in bytes
* @element_count: Maximum number of elements to be stored
- * Returns:
- * integer: < 0 for error, >= 0 for success
- * Description:
+ *
* (Re)Allocates internal memory for the given ammount of elements
* at the given individual size
+ *
+ * Returns:
+ * integer: < 0 for error, >= 0 for success
* Notes:
* If this function gets called when the buffer already has internal
* memory (buffer is setup), that memory gets freed automatically.
@@ -304,12 +297,12 @@ int kiro_trb_reshape (KiroTrb *trb, uint64_t element_size, uint64_t element_coun
/**
* kiro_trb_clone:
- * Clones the given memory into the internal memory
- * @trb: #KiroTrb to perform the operation on
+ * @trb: (transfer none); #KiroTrb to perform the operation on
* @source: Pointer to the source memory to clone from
- * Description:
+ *
* Interprets the given memory as a pointer to another KIRO TRB and
* tries to copy that memory into its own.
+ *
* Notes:
* The given memory is treated as a correct KIRO TRB memory block,
* including a consistent memory header. That header is read and
@@ -327,11 +320,11 @@ int kiro_trb_clone (KiroTrb *trb, void *source);
/**
* kiro_trb_push:
- * Adds an element into the buffer
- * @trb: #KiroTrb to perform the operation on
+ * @trb: (transfer none): #KiroTrb to perform the operation on
* @source: Pointer to the memory of the element to add
- * Description:
+ *
* Copies the given element and adds it into the buffer
+ *
* Notes:
* This function will read n-Bytes from the given address according
* to the setup element_size. The read memory is copied directly
@@ -348,11 +341,11 @@ int kiro_trb_push (KiroTrb *trb, void *source);
/**
* kiro_trb_refresh:
- * Re-reads the TRBs memory header
- * @trb: #KiroTrb to perform the operation on
- * Description:
+ * @trb: (transfer none): #KiroTrb to perform the operation on
+ *
* Re-reads the internal memory header and sets up all pointers
* and counters in accordance to these information
+ *
* Notes:
* This function is used in case the TRBs memory got changed
* directly (For example, by a DMA operation) to make the TRB
@@ -367,12 +360,12 @@ void kiro_trb_refresh (KiroTrb *trb);
/**
* kiro_trb_adopt:
- * Adopts the given memory into the TRB
- * @trb: #KiroTrb to perform the operation on
+ * @trb: (transfer none): #KiroTrb to perform the operation on
* @source: Pointer to the source memory to adopt
- * Description:
+ *
* Interprets the given memory as a pointer to another KIRO TRB and
* takes ownership over the memory.
+ *
* Notes:
* The given memory is treated as a correct KIRO TRB memory block,
* including a consistent memory header. That header is read and
--
cgit v1.2.3