X-Git-Url: https://git.saurik.com/apple/libdispatch.git/blobdiff_plain/e85f44377864e428703fb21503e29f422c11288f..9d9a7e41279eb3e17c326c333f21dd7cbf02cfdd:/man/dispatch_source_create.3?ds=sidebyside

diff --git a/man/dispatch_source_create.3 b/man/dispatch_source_create.3
index 1d774a9..b4e9a7a 100644
--- 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
@@ -25,6 +25,16 @@
 .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)"
@@ -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
-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.
@@ -102,10 +113,14 @@ DISPATCH_SOURCE_TYPE_DATA_ADD
 .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_MEMORYPRESSURE
+.It
 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
-.Vt DISPATCH_SOURCE_TYPE_DATA_ADD
-and
+.Vt DISPATCH_SOURCE_TYPE_DATA_ADD ,
 .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
-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
-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
@@ -189,12 +230,39 @@ on the
 .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
-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
@@ -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 ,
-.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
-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
@@ -251,9 +320,12 @@ The port's corresponding receive right has been destroyed
 .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.
+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
@@ -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
+.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.
@@ -285,16 +391,13 @@ The process has become another executable image via a call to
 .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
-indicates which of the events in the
+is a bitmask that indicates which of the events in the
 .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
-queue on an interval specified by
-.Fn dispatch_source_set_timer .
-The
+queue. The
 .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
-The function
+The timer parameters are configured with the
 .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
-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 ,
-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 ,
-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
@@ -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
-A write to the referenced file occurred
+A write to the referenced file occurred.
 .It \(bu DISPATCH_VNODE_EXTEND
-The referenced file was extended
+The referenced file was extended.
 .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
-The link count on the referenced node has changed
+The link count on the referenced node has changed.
 .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_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
-indicates which of the events in the
+is a bitmask that indicates which of the events in the
 .Fa mask
 were observed.
 .Pp