os_activity_initiate(3)  BSD Library Functions Manual  os_activity_initiate(3)

NAME
     os_activity_initiate, os_activity_initiate_f -- 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));

DESCRIPTION
     An activity is essentially an identifier that is created by the system.
     The identifier is transported with work via GCD, XPC and other mecha-
     nisms.  The identifier simplifies debugging programs since it correlates
     the trace and 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
     constant 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 the block or func-
     tion with a new activity.

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
     os_trace(3), os_log(3)

Darwin                         November 14, 2024                        Darwin