os_activity_initiate(3)

NAME
os_activity_initiate, os_activity_initiate_f, os_activity_start, os_activity_end - activity related routines

SYNOPSIS
#include <os/activity.h>
void
os_activity_initiate(const char *description, uint32_t flags, void (^activity_block)(void));
void
os_activity_initiate_f(const char *description, uint32_t flags, void *ctx, void function(void *ctx));
os_activity_t
os_activity_start(const char *description, uint32_t flags);
void
os_activity_end(os_activity_t activity);

DESCRIPTION
An activity is essentially an identifier that is created by the system. The identifier is transported with work via GCD, XPC and other mechanisms. Activities also have a ring buffer associated with them to log all related os_trace(3) messages. This technique makes debugging a programs easier since it correlates the log messages to the area in question. Although an activity appears to have a start/end, it is only finished when no other work related to it is enqueued to be processed. Activity functions only allow static strings for performance and privacy, similar to os_trace(3).

Supported Activity Name:

    os_activity_initiate("indexing database", OS_ACTIVITY_FLAG_DEFAULT, ^(void) {
    	[self indexDatabase];
    });

Unsupported Activity Name:

    snprintf(buffer, "indexing database for %s", username);
    os_activity_initiate(buffer, OS_ACTIVITY_FLAG_DEFAULT, ^(void) {
    	[self indexDatabase];
    });

os_activity_initiate and os_activity_initiate_f wraps a new activity begin and end in a simple call. Useful if caller does not care about identifier.

os_activity_start and os_activity_end can be used for situations where a context is involved or work is handled asynchronously. Calling os_activity_end with the result from os_activity_start only signifies that control returned to the caller. An activity is not "complete" until all enqueued work is finished.

EXAMPLES
Example use of activity with a message.

    #include <os/trace.h>
    #include <os/activity.h>
    - (IBOutlet) indexDatabase:(id) sender {
    	os_activity_initiate("index database", OS_ACTIVITY_FLAG_DEFAULT, ^{
    		os_trace("re-indexing database for %d", self.uid);

    		[self reIndex: self.uid];
    	});
    }

SEE ALSO
ostraceutil(1), os_trace(3)