diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/kiro-client.c | 9 | ||||
| -rw-r--r-- | src/kiro-client.h | 84 | ||||
| -rw-r--r-- | src/kiro-rdma.h | 31 | ||||
| -rw-r--r-- | src/kiro-sb.c | 11 | ||||
| -rw-r--r-- | src/kiro-sb.h | 125 | ||||
| -rw-r--r-- | src/kiro-server.c | 9 | ||||
| -rw-r--r-- | src/kiro-server.h | 40 | ||||
| -rw-r--r-- | src/kiro-trb.c | 11 | ||||
| -rw-r--r-- | 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 |