diff options
Diffstat (limited to 'src/kiro-sb.h')
| -rw-r--r-- | src/kiro-sb.h | 125 |
1 files changed, 65 insertions, 60 deletions
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 |