Progress notification system for asynchronous operations

Progress notification system for asynchronous operations — Values representing progress

Synopsis

typedef             OstreeAsyncProgress;
OstreeAsyncProgress * ostree_async_progress_new         (void);
OstreeAsyncProgress * ostree_async_progress_new_and_connect
                                                        (void (*changed) (OstreeAsyncProgress *self, gpointer user_data),
                                                         gpointer user_data);
char *              ostree_async_progress_get_status    (OstreeAsyncProgress *self);
void                ostree_async_progress_get           (OstreeAsyncProgress *self,
                                                         ...);
GVariant *          ostree_async_progress_get_variant   (OstreeAsyncProgress *self,
                                                         const char *key);
guint               ostree_async_progress_get_uint      (OstreeAsyncProgress *self,
                                                         const char *key);
guint64             ostree_async_progress_get_uint64    (OstreeAsyncProgress *self,
                                                         const char *key);
void                ostree_async_progress_set_status    (OstreeAsyncProgress *self,
                                                         const char *status);
void                ostree_async_progress_set           (OstreeAsyncProgress *self,
                                                         ...);
void                ostree_async_progress_set_variant   (OstreeAsyncProgress *self,
                                                         const char *key,
                                                         GVariant *value);
void                ostree_async_progress_set_uint      (OstreeAsyncProgress *self,
                                                         const char *key,
                                                         guint value);
void                ostree_async_progress_set_uint64    (OstreeAsyncProgress *self,
                                                         const char *key,
                                                         guint64 value);
void                ostree_async_progress_finish        (OstreeAsyncProgress *self);

Description

For many asynchronous operations, it's desirable for callers to be able to watch their status as they progress. For example, an user interface calling an asynchronous download operation will want to be able to see the total number of bytes downloaded.

This class provides a mechanism for callees of asynchronous operations to communicate back with callers. It transparently handles thread safety, ensuring that the progress change notification occurs in the thread-default context of the calling operation.

The ostree_async_progress_get_status() and ostree_async_progress_set_status() methods get and set a well-known `status` key of type G_VARIANT_TYPE_STRING. This key may be accessed using the other OstreeAsyncProgress methods, but it must always have the correct type.

Details

OstreeAsyncProgress

typedef struct OstreeAsyncProgress   OstreeAsyncProgress;

ostree_async_progress_new ()

OstreeAsyncProgress * ostree_async_progress_new         (void);

Returns :

A new progress object. [transfer full]

ostree_async_progress_new_and_connect ()

OstreeAsyncProgress * ostree_async_progress_new_and_connect
                                                        (void (*changed) (OstreeAsyncProgress *self, gpointer user_data),
                                                         gpointer user_data);

ostree_async_progress_get_status ()

char *              ostree_async_progress_get_status    (OstreeAsyncProgress *self);

Get the human-readable status string from the OstreeAsyncProgress. This operation is thread-safe. The retuned value may be NULL if no status is set.

This is a convenience function to get the well-known `status` key.

self :

an OstreeAsyncProgress

Returns :

the current status, or NULL if none is set. [transfer full][nullable]

Since 2017.6


ostree_async_progress_get ()

void                ostree_async_progress_get           (OstreeAsyncProgress *self,
                                                         ...);

Get the values corresponding to zero or more keys from the OstreeAsyncProgress. Each key is specified in @... as the key name, followed by a GVariant format string, followed by the necessary arguments for that format string, just as for g_variant_get(). After those arguments is the next key name. The varargs list must be NULL-terminated.

Each format string must make deep copies of its value, as the values stored in the OstreeAsyncProgress may be freed from another thread after this function returns.

This operation is thread-safe, and all the keys are queried atomically.

1
2
3
4
5
6
7
8
9
10
11
guint32 outstanding_fetches;
guint64 bytes_received;
g_autofree gchar *status = NULL;
g_autoptr(GVariant) refs_variant = NULL;

ostree_async_progress_get (progress,
                           "outstanding-fetches", "u", &outstanding_fetches,
                           "bytes-received", "t", &bytes_received,
                           "status", "s", &status,
                           "refs", "@a{ss}", &refs_variant,
                           NULL);

self :

an OstreeAsyncProgress

... :

key name, format string, GVariant return locations, …, followed by NULL

Since 2017.6


ostree_async_progress_get_variant ()

GVariant *          ostree_async_progress_get_variant   (OstreeAsyncProgress *self,
                                                         const char *key);

Look up a key in the OstreeAsyncProgress and return the GVariant associated with it. The lookup is thread-safe.

self :

an OstreeAsyncProgress

key :

a key to look up

Returns :

value for the given key, or NULL if it was not set. [transfer full][nullable]

Since 2017.6


ostree_async_progress_get_uint ()

guint               ostree_async_progress_get_uint      (OstreeAsyncProgress *self,
                                                         const char *key);

ostree_async_progress_get_uint64 ()

guint64             ostree_async_progress_get_uint64    (OstreeAsyncProgress *self,
                                                         const char *key);

ostree_async_progress_set_status ()

void                ostree_async_progress_set_status    (OstreeAsyncProgress *self,
                                                         const char *status);

Set the human-readable status string for the OstreeAsyncProgress. This operation is thread-safe. NULL may be passed to clear the status.

This is a convenience function to set the well-known `status` key.

self :

an OstreeAsyncProgress

status :

new status string, or NULL to clear the status. [nullable]

Since 2017.6


ostree_async_progress_set ()

void                ostree_async_progress_set           (OstreeAsyncProgress *self,
                                                         ...);

Set the values for zero or more keys in the OstreeAsyncProgress. Each key is specified in @... as the key name, followed by a GVariant format string, followed by the necessary arguments for that format string, just as for g_variant_new(). After those arguments is the next key name. The varargs list must be NULL-terminated.

g_variant_ref_sink() will be called as appropriate on the GVariant parameters, so they may be floating.

This operation is thread-safe, and all the keys are set atomically.

1
2
3
4
5
6
7
8
9
guint32 outstanding_fetches = 15;
guint64 bytes_received = 1000;

ostree_async_progress_set (progress,
                           "outstanding-fetches", "u", outstanding_fetches,
                           "bytes-received", "t", bytes_received,
                           "status", "s", "Updated status",
                           "refs", "@a{ss}", g_variant_new_parsed ("@a{ss} {}"),
                           NULL);

self :

an OstreeAsyncProgress

... :

key name, format string, GVariant parameters, …, followed by NULL

Since 2017.6


ostree_async_progress_set_variant ()

void                ostree_async_progress_set_variant   (OstreeAsyncProgress *self,
                                                         const char *key,
                                                         GVariant *value);

Assign a new value to the given key, replacing any existing value. The operation is thread-safe. value may be a floating reference; g_variant_ref_sink() will be called on it.

Any watchers of the OstreeAsyncProgress will be notified of the change if value differs from the existing value for key.

self :

an OstreeAsyncProgress

key :

a key to set

value :

the value to assign to key

Since 2017.6


ostree_async_progress_set_uint ()

void                ostree_async_progress_set_uint      (OstreeAsyncProgress *self,
                                                         const char *key,
                                                         guint value);

ostree_async_progress_set_uint64 ()

void                ostree_async_progress_set_uint64    (OstreeAsyncProgress *self,
                                                         const char *key,
                                                         guint64 value);

ostree_async_progress_finish ()

void                ostree_async_progress_finish        (OstreeAsyncProgress *self);

Process any pending signals, ensuring the main context is cleared of sources used by this object. Also ensures that no further events will be queued.

self :

Self