libdispatch-913.30.4.tar.gz

[apple/libdispatch.git] / man / dispatch_source_create.3

diff --git a/man/dispatch_source_create.3 b/man/dispatch_source_create.3
index 1d774a9677ee763df2dfef7fb609f40a1c2dba49..b4e9a7ad8e93796553f4fd417101abeb4b324efe 100644 (file)
--- a/man/dispatch_source_create.3
+++ b/man/dispatch_source_create.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2008-2010 Apple Inc. All rights reserved.
+.\" Copyright (c) 2008-2013 Apple Inc. All rights reserved.

 .Dd May 1, 2009
 .Dt dispatch_source_create 3
 .Os Darwin
 .Dd May 1, 2009
 .Dt dispatch_source_create 3
 .Os Darwin


@@ -25,6 +25,16 @@
 .Fa "void (*function)(void *)"
 .Fc
 .Ft void
 .Fa "void (*function)(void *)"
 .Fc
 .Ft void

+.Fo dispatch_source_set_registration_handler
+.Fa "dispatch_source_t source"
+.Fa "void (^block)(void)"
+.Fc
+.Ft void
+.Fo dispatch_source_set_registration_handler_f
+.Fa "dispatch_source_t source"
+.Fa "void (*function)(void *)"
+.Fc
+.Ft void

 .Fo dispatch_source_set_cancel_handler
 .Fa "dispatch_source_t source"
 .Fa "void (^block)(void)"
 .Fo dispatch_source_set_cancel_handler
 .Fa "dispatch_source_t source"
 .Fa "void (^block)(void)"


@@ -90,7 +100,8 @@ constant to use the default target queue (the default priority global
 concurrent queue).
 .Pp
 Newly created sources are created in a suspended state. After the source has
 concurrent queue).
 .Pp
 Newly created sources are created in a suspended state. After the source has

-been configured by setting an event handler, cancellation handler, context,
+been configured by setting an event handler, cancellation handler, registration
+handler, context,

 etc., the source must be activated by a call to
 .Fn dispatch_resume
 before any events will be delivered.
 etc., the source must be activated by a call to
 .Fn dispatch_resume
 before any events will be delivered.


@@ -102,10 +113,14 @@ DISPATCH_SOURCE_TYPE_DATA_ADD
 .It
 DISPATCH_SOURCE_TYPE_DATA_OR
 .It
 .It
 DISPATCH_SOURCE_TYPE_DATA_OR
 .It

+DISPATCH_SOURCE_TYPE_DATA_REPLACE
+.It

 DISPATCH_SOURCE_TYPE_MACH_SEND
 .It
 DISPATCH_SOURCE_TYPE_MACH_RECV
 .It
 DISPATCH_SOURCE_TYPE_MACH_SEND
 .It
 DISPATCH_SOURCE_TYPE_MACH_RECV
 .It

+DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
+.It

 DISPATCH_SOURCE_TYPE_PROC
 .It
 DISPATCH_SOURCE_TYPE_READ
 DISPATCH_SOURCE_TYPE_PROC
 .It
 DISPATCH_SOURCE_TYPE_READ


@@ -155,19 +170,45 @@ The result of calling this function from any other context is undefined.
 The
 .Fn dispatch_source_merge_data
 function is intended for use with the
 The
 .Fn dispatch_source_merge_data
 function is intended for use with the

-.Vt DISPATCH_SOURCE_TYPE_DATA_ADD
-and
+.Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,

 .Vt DISPATCH_SOURCE_TYPE_DATA_OR
 .Vt DISPATCH_SOURCE_TYPE_DATA_OR

+and
+.Vt DISPATCH_SOURCE_TYPE_DATA_REPLACE

 source types. The result of using this function with any other source type is
 source types. The result of using this function with any other source type is

-undefined. Calling this function will atomically add or logical OR the data
-into the source's data, and trigger the delivery of the source's event handler.
+undefined. Data merging is performed according to the source type:
+.Bl -tag -width "XXDISPATCH_SOURCE_TYPE_DATA_REPLACE" -compact -offset indent
+.It \(bu DISPATCH_SOURCE_TYPE_DATA_ADD
+.Vt data
+is atomically added to the source's data
+.It \(bu DISPATCH_SOURCE_TYPE_DATA_OR
+.Vt data
+is atomically bitwise ORed into the source's data
+.It \(bu DISPATCH_SOURCE_TYPE_DATA_REPLACE
+.Vt data
+atomically replaces the source's data.
+.El
+.Pp
+If the source data value resulting from the merge operation is 0, the source
+handler will not be invoked. This can happen if:
+.Bl -bullet -compact -offset indent
+.It
+the atomic addition wraps for sources of type
+.Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
+.It
+0 is merged for sources of type
+.Vt DISPATCH_SOURCE_TYPE_DATA_REPLACE .
+.El

 .Pp
 .Sh SOURCE EVENT HANDLERS
 In order to receive events from the dispatch source, an event handler should be
 specified via
 .Fn dispatch_source_set_event_handler .
 The event handler block is submitted to the source's target queue when the state
 .Pp
 .Sh SOURCE EVENT HANDLERS
 In order to receive events from the dispatch source, an event handler should be
 specified via
 .Fn dispatch_source_set_event_handler .
 The event handler block is submitted to the source's target queue when the state

-of the underlying system handle changes, or when an event occurs.
+of the underlying system handle changes, or when an event occurs. If a source
+is resumed with no event handler block set, events will be quietly ignored.
+If the event handler block is changed while the source is suspended, or from a
+block running on a serial queue that is the source's target queue, then the next
+event handler invocation will use the new block.

 .Pp
 Dispatch sources may be suspended or resumed independently of their target
 queues using
 .Pp
 Dispatch sources may be suspended or resumed independently of their target
 queues using


@@ -189,12 +230,39 @@ on the
 .Fa handler
 block.
 .Pp
 .Fa handler
 block.
 .Pp

+To unset the event handler, call
+.Fn dispatch_source_set_event_handler_f
+and pass NULL as
+.Fa function .
+This unsets the event handler regardless of whether the handler
+was a function pointer or a block. Registration and cancellation handlers
+(see below) may be unset in the same way, but as noted below, a cancellation
+handler may be required.
+.Sh REGISTRATION
+When 
+.Fn dispatch_resume
+is called on a suspended or newly created source, there may be a brief delay
+before the source is ready to receive events from the underlying system handle.
+During this delay, the event handler will not be invoked, and events will be
+missed.
+.Pp
+Once the dispatch source is registered with the underlying system and is ready
+to process all events its optional registration handler will be submitted to
+its target queue. This registration handler may be specified via
+.Fn dispatch_source_set_registration_handler .
+.Pp
+The event handler will not be called until the registration handler finishes.
+If the source is canceled (see below) before it is registered,
+its registration handler will not be called.
+.Pp

 .Sh CANCELLATION
 The
 .Fn dispatch_source_cancel
 function asynchronously cancels the dispatch source, preventing any further
 invocation of its event handler block. Cancellation does not interrupt a
 .Sh CANCELLATION
 The
 .Fn dispatch_source_cancel
 function asynchronously cancels the dispatch source, preventing any further
 invocation of its event handler block. Cancellation does not interrupt a

-currently executing handler block (non-preemptive).
+currently executing handler block (non-preemptive). If a source is canceled
+before the first time it is resumed, its event handler will never be called.
+(In this case, note that the source must be resumed before it can be released.)

 .Pp
 The
 .Fn dispatch_source_testcancel
 .Pp
 The
 .Fn dispatch_source_testcancel


@@ -221,14 +289,15 @@ The following section contains a summary of supported dispatch event types and
 the interpretation of their parameters and returned data.
 .Pp
 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
 the interpretation of their parameters and returned data.
 .Pp
 .Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,

-.Vt DISPATCH_SOURCE_TYPE_DATA_OR
+.Vt DISPATCH_SOURCE_TYPE_DATA_OR ,
+.Vt DISPATCH_SOURCE_TYPE_DATA_REPLACE

 .Pp
 Sources of this type allow applications to manually trigger the source's event
 handler via a call to
 .Fn dispatch_source_merge_data .
 The data will be merged with the source's pending data via an atomic add or
 .Pp
 Sources of this type allow applications to manually trigger the source's event
 handler via a call to
 .Fn dispatch_source_merge_data .
 The data will be merged with the source's pending data via an atomic add or

-logic OR (based on the source's type), and the event handler block will be
-submitted to the source's target queue. The
+atomic bitwise OR, or direct replacement (based on the source's type), and the
+event handler block will be submitted to the source's target queue. The

 .Fa data
 is application defined. These sources have no
 .Fa handle
 .Fa data
 is application defined. These sources have no
 .Fa handle


@@ -251,9 +320,12 @@ The port's corresponding receive right has been destroyed
 .Pp
 The data returned by
 .Fn dispatch_source_get_data
 .Pp
 The data returned by
 .Fn dispatch_source_get_data

-indicates which of the events in the
+is a bitmask that indicates which of the events in the

 .Fa mask
 .Fa mask

-were observed.
+were observed.  Note that because this source type will request notifications on
+the provided port, it should not be mixed with the use of
+.Fn mach_port_request_notification
+on the same port.

 .Pp
 .Vt DISPATCH_SOURCE_TYPE_MACH_RECV
 .Pp
 .Pp
 .Vt DISPATCH_SOURCE_TYPE_MACH_RECV
 .Pp


@@ -266,6 +338,40 @@ is unused and should be zero.
 The event handler block will be submitted to the target queue when a message
 on the mach port is waiting to be received.
 .Pp
 The event handler block will be submitted to the target queue when a message
 on the mach port is waiting to be received.
 .Pp

+.Vt DISPATCH_SOURCE_TYPE_MEMORYPRESSURE
+.Pp
+Sources of this type monitor the system memory pressure condition for state
+changes.  The
+.Fa handle
+is unused and should be zero. The
+.Fa mask
+may be one or more of the following:
+.Bl -tag -width "XXDISPATCH_MEMORYPRESSURE_CRITICAL" -compact -offset indent
+.It \(bu DISPATCH_MEMORYPRESSURE_NORMAL
+The system memory pressure condition has returned to normal.
+.It \(bu DISPATCH_MEMORYPRESSURE_WARN
+The system memory pressure condition has changed to warning.
+.It \(bu DISPATCH_MEMORYPRESSURE_CRITICAL
+The system memory pressure condition has changed to critical.
+.El
+.Pp
+The data returned by
+.Fn dispatch_source_get_data
+indicates which of the events in the
+.Fa mask
+were observed.
+.Pp
+Elevated memory pressure is a system-wide condition that applications
+registered for this source should react to by changing their future memory use
+behavior, e.g. by reducing cache sizes of newly initiated operations until
+memory pressure returns back to normal.
+.Pp
+However, applications should
+.Em NOT
+traverse and discard existing caches for past operations when the system memory
+pressure enters an elevated state, as that is likely to trigger VM operations
+that will further aggravate system memory pressure.
+.Pp

 .Vt DISPATCH_SOURCE_TYPE_PROC
 .Pp
 Sources of this type monitor processes for state changes.
 .Vt DISPATCH_SOURCE_TYPE_PROC
 .Pp
 Sources of this type monitor processes for state changes.


@@ -285,16 +391,13 @@ The process has become another executable image via a call to
 .Xr execve 2
 or
 .Xr posix_spawn 2 .
 .Xr execve 2
 or
 .Xr posix_spawn 2 .

-.It \(bu DISPATCH_PROC_REAP
-The process status has been collected by its parent process via
-.Xr wait 2 .

 .It \(bu DISPATCH_PROC_SIGNAL
 A signal was delivered to the process.
 .El
 .Pp
 The data returned by
 .Fn dispatch_source_get_data
 .It \(bu DISPATCH_PROC_SIGNAL
 A signal was delivered to the process.
 .El
 .Pp
 The data returned by
 .Fn dispatch_source_get_data

-indicates which of the events in the
+is a bitmask that indicates which of the events in the

 .Fa mask
 were observed.
 .Pp
 .Fa mask
 were observed.
 .Pp


@@ -355,57 +458,71 @@ signal(SIGTERM, SIG_IGN);
 .Vt DISPATCH_SOURCE_TYPE_TIMER
 .Pp
 Sources of this type periodically submit the event handler block to the target
 .Vt DISPATCH_SOURCE_TYPE_TIMER
 .Pp
 Sources of this type periodically submit the event handler block to the target

-queue on an interval specified by
-.Fn dispatch_source_set_timer .
-The
+queue. The

 .Fa handle
 .Fa handle

-and
-.Fa mask
-arguments are unused and should be zero.
-.Pp
-A best effort attempt is made to submit the event handler block to the target
-queue at the specified time; however, actual invocation may occur at a later
-time.
+argument is unused and should be zero.

 .Pp
 The data returned by
 .Fn dispatch_source_get_data
 is the number of times the timer has fired since the last invocation of the
 event handler block.
 .Pp
 .Pp
 The data returned by
 .Fn dispatch_source_get_data
 is the number of times the timer has fired since the last invocation of the
 event handler block.
 .Pp

-The function
+The timer parameters are configured with the

 .Fn dispatch_source_set_timer
 .Fn dispatch_source_set_timer

-takes as an argument the
+function. Once this function returns, any pending source data accumulated for
+the previous timer parameters has been cleared; the next fire of the timer will
+occur at
+.Fa start ,
+and every
+.Fa interval
+nanoseconds thereafter until the timer source is canceled.
+.Pp
+Any fire of the timer may be delayed by the system in order to improve power
+consumption and system performance. The upper limit to the allowable delay may
+be configured with the
+.Fa leeway
+argument, the lower limit is under the control of the system.
+.Pp
+For the initial timer fire at
+.Fa start ,
+the upper limit to the allowable delay is set to
+.Fa leeway
+nanoseconds. For the subsequent timer fires at

 .Fa start
 .Fa start

-time of the timer (initial fire time) represented as a
-.Vt dispatch_time_t .
-The timer dispatch source will use the same clock as the function used to
-create this value. (See
-.Xr dispatch_time 3
-for more information.) The
+.Li "+ N *"

 .Fa interval ,
 .Fa interval ,

-in nanoseconds, specifies the period at which the timer should repeat. All
-timers will repeat indefinitely until
-.Fn dispatch_source_cancel
-is called. The
+the upper limit is
+.Li MIN(

 .Fa leeway ,
 .Fa leeway ,

-in nanoseconds, is a hint to the system that it may defer the timer in order to
-align with other system activity for improved system performance or reduced
-power consumption. (For example, an application might perform a periodic task
-every 5 minutes with a leeway of up to 30 seconds.) Note that some latency is
-to be expected for all timers even when a value of zero is used.
-.Pp
-.Em Note :
-Under the C language, untyped numbers default to the
-.Vt int
-type. This can lead to truncation bugs when arithmetic operations with other
-numbers are expected to generate a
-.Vt uint64_t
-sized result. When in doubt, use
-.Vt ull
-as a suffix. For example:
-.Bd -literal -offset indent
-3ull * NSEC_PER_SEC
-.Ed
+.Fa interval
+.Li "/ 2 )" .
+.Pp
+The lower limit to the allowable delay may vary with process state such as
+visibility of application UI. If the specified timer source was created with a
+.Fa mask
+of
+.Vt DISPATCH_TIMER_STRICT ,
+the system will make a best effort to strictly observe the provided
+.Fa leeway
+value even if it is smaller than the current lower limit. Note that a minimal
+amount of delay is to be expected even if this flag is specified.
+.Pp
+The
+.Fa start
+argument also determines which clock will be used for the timer: If
+.Fa start
+is
+.Vt DISPATCH_TIME_NOW
+or was created with
+.Xr dispatch_time 3 ,
+the timer is based on
+.Fn mach_absolute_time .
+If
+.Fa start
+was created with
+.Xr dispatch_walltime 3 ,
+the timer is based on
+.Xr gettimeofday 3 .

 .Pp
 .Vt DISPATCH_SOURCE_TYPE_VNODE
 .Pp
 .Pp
 .Vt DISPATCH_SOURCE_TYPE_VNODE
 .Pp


@@ -421,24 +538,29 @@ may be one or more of the following:
 The referenced node was removed from the filesystem namespace via
 .Xr unlink 2 .
 .It \(bu DISPATCH_VNODE_WRITE
 The referenced node was removed from the filesystem namespace via
 .Xr unlink 2 .
 .It \(bu DISPATCH_VNODE_WRITE

-A write to the referenced file occurred
+A write to the referenced file occurred.

 .It \(bu DISPATCH_VNODE_EXTEND
 .It \(bu DISPATCH_VNODE_EXTEND

-The referenced file was extended
+The referenced file was extended.

 .It \(bu DISPATCH_VNODE_ATTRIB
 .It \(bu DISPATCH_VNODE_ATTRIB

-The metadata attributes of the referenced node have changed
+The metadata attributes of the referenced node have changed.

 .It \(bu DISPATCH_VNODE_LINK
 .It \(bu DISPATCH_VNODE_LINK

-The link count on the referenced node has changed
+The link count on the referenced node has changed.

 .It \(bu DISPATCH_VNODE_RENAME
 .It \(bu DISPATCH_VNODE_RENAME

-The referenced node was renamed
+The referenced node was renamed.

 .It \(bu DISPATCH_VNODE_REVOKE
 Access to the referenced node was revoked via
 .Xr revoke 2
 or the underlying fileystem was unmounted.
 .It \(bu DISPATCH_VNODE_REVOKE
 Access to the referenced node was revoked via
 .Xr revoke 2
 or the underlying fileystem was unmounted.

+.It \(bu DISPATCH_VNODE_FUNLOCK
+The referenced file was unlocked by
+.Xr flock 2
+or
+.Xr close 2 .

 .El
 .Pp
 The data returned by
 .Fn dispatch_source_get_data
 .El
 .Pp
 The data returned by
 .Fn dispatch_source_get_data

-indicates which of the events in the
+is a bitmask that indicates which of the events in the

 .Fa mask
 were observed.
 .Pp
 .Fa mask
 were observed.
 .Pp