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 0a38cd29407cdbecd7dfe35617de41a9cd25f66e..b4e9a7ad8e93796553f4fd417101abeb4b324efe 100644 (file)
--- a/man/dispatch_source_create.3
+++ b/man/dispatch_source_create.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2008-2009 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)"


@@ -38,7 +48,7 @@
 .Fo dispatch_source_cancel
 .Fa "dispatch_source_t source"
 .Fc
 .Fo dispatch_source_cancel
 .Fa "dispatch_source_t source"
 .Fc

-.Ft void
+.Ft long

 .Fo dispatch_source_testcancel
 .Fa "dispatch_source_t source"
 .Fc
 .Fo dispatch_source_testcancel
 .Fa "dispatch_source_t source"
 .Fc


@@ -67,7 +77,7 @@
 .Fa "uint64_t leeway"
 .Fc
 .Sh DESCRIPTION
 .Fa "uint64_t leeway"
 .Fc
 .Sh DESCRIPTION

-Dispatch event sources may be used to monitor a variety of system objects and 
+Dispatch event sources may be used to monitor a variety of system objects and

 events including file descriptors, mach ports, processes, virtual filesystem
 nodes, signal delivery and timers.
 .Pp
 events including file descriptors, mach ports, processes, virtual filesystem
 nodes, signal delivery and timers.
 .Pp


@@ -81,9 +91,18 @@ with calls to
 .Fn dispatch_retain
 and
 .Fn dispatch_release
 .Fn dispatch_retain
 and
 .Fn dispatch_release

-respectively. Newly created sources are created in a suspended state. After the
-source has been configured by setting an event handler, cancellation handler,
-context, etc., the source must be activated by a call to
+respectively. The
+.Fa queue
+parameter specifies the target queue of the new source object, it will
+be retained by the source object. Pass the
+.Dv DISPATCH_TARGET_QUEUE_DEFAULT
+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, registration
+handler, context,
+etc., the source must be activated by a call to

 .Fn dispatch_resume
 before any events will be delivered.
 .Pp
 .Fn dispatch_resume
 before any events will be delivered.
 .Pp


@@ -94,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


@@ -117,21 +140,21 @@ and
 .Fa mask
 arguments to
 .Fn dispatch_source_create
 .Fa mask
 arguments to
 .Fn dispatch_source_create

-and the return values of the 
+and the return values of the

 .Fn dispatch_source_get_handle ,
 .Fn dispatch_source_get_mask ,
 and
 .Fn dispatch_source_get_handle ,
 .Fn dispatch_source_get_mask ,
 and

-.Fn dispatch_source_get_data 
+.Fn dispatch_source_get_data

 functions should be interpreted according to the type of the dispatch source.
 .Pp
 functions should be interpreted according to the type of the dispatch source.
 .Pp

-The 
+The

 .Fn dispatch_source_get_handle
 function
 returns the underlying handle to the dispatch source (i.e. file descriptor,
 mach port, process identifer, etc.). The result of this function may be cast
 directly to the underlying type.
 .Pp
 .Fn dispatch_source_get_handle
 function
 returns the underlying handle to the dispatch source (i.e. file descriptor,
 mach port, process identifer, etc.). The result of this function may be cast
 directly to the underlying type.
 .Pp

-The 
+The

 .Fn dispatch_source_get_mask
 function
 returns the set of flags that were specified at source creation time via the
 .Fn dispatch_source_get_mask
 function
 returns the set of flags that were specified at source creation time via the


@@ -147,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


@@ -175,18 +224,45 @@ block
 need not be reentrant safe, as it is not resubmitted to the target
 .Fa queue
 until any prior invocation for that dispatch source has completed.
 need not be reentrant safe, as it is not resubmitted to the target
 .Fa queue
 until any prior invocation for that dispatch source has completed.

-When the hander is set, the dispatch source will perform a
+When the handler is set, the dispatch source will perform a

 .Fn Block_copy
 on the
 .Fa handler
 block.
 .Pp
 .Fn Block_copy
 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
 .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


@@ -205,7 +281,7 @@ a cancellation handler is required for file descriptor and mach port based
 sources in order to safely close the descriptor or destroy the port. Closing the
 descriptor or port before the cancellation handler has run may result in a race
 condition: if a new descriptor is allocated with the same value as the recently
 sources in order to safely close the descriptor or destroy the port. Closing the
 descriptor or port before the cancellation handler has run may result in a race
 condition: if a new descriptor is allocated with the same value as the recently

-cosed descriptor while the source's event handler is still running, the event
+closed descriptor while the source's event handler is still running, the event

 handler may read/write data to the wrong descriptor.
 .Pp
 .Sh DISPATCH SOURCE TYPES
 handler may read/write data to the wrong descriptor.
 .Pp
 .Sh DISPATCH SOURCE TYPES


@@ -213,19 +289,20 @@ 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
 .Pp
 Sources of this type allow applications to manually trigger the source's event

-handler via a call to 
+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
 .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
-.Fa mask
-and
+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
 .Fa data

-are application defined. These sources have no
+is application defined. These sources have no

 .Fa handle
 .Fa handle

+or
+.Fa mask

 and zero should be used.
 .Pp
 .Vt DISPATCH_SOURCE_TYPE_MACH_SEND
 and zero should be used.
 .Pp
 .Vt DISPATCH_SOURCE_TYPE_MACH_SEND


@@ -243,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


@@ -258,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.


@@ -268,7 +382,7 @@ is the process identifier (pid_t) of the process to monitor and the
 may be one or more of the following:
 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
 .It \(bu DISPATCH_PROC_EXIT
 may be one or more of the following:
 .Bl -tag -width "XXDISPATCH_PROC_SIGNAL" -compact -offset indent
 .It \(bu DISPATCH_PROC_EXIT

-The process has exited and is available to 
+The process has exited and is available to

 .Xr wait 2 .
 .It \(bu DISPATCH_PROC_FORK
 The process has created one or more child processes.
 .Xr wait 2 .
 .It \(bu DISPATCH_PROC_FORK
 The process has created one or more child processes.


@@ -277,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


@@ -309,7 +420,7 @@ will be performed.
 .Pp
 Users of this source type are strongly encouraged to perform non-blocking I/O
 and handle any truncated reads or error conditions that may occur. See
 .Pp
 Users of this source type are strongly encouraged to perform non-blocking I/O
 and handle any truncated reads or error conditions that may occur. See

-.Xr fnctl 2
+.Xr fcntl 2

 for additional information about setting the
 .Vt O_NONBLOCK
 flag on a file descriptor.
 for additional information about setting the
 .Vt O_NONBLOCK
 flag on a file descriptor.


@@ -347,64 +458,78 @@ 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
 Sources of this type monitor the virtual filesystem nodes for state changes.
 The
 .Fa handle
 .Pp
 .Vt DISPATCH_SOURCE_TYPE_VNODE
 .Pp
 Sources of this type monitor the virtual filesystem nodes for state changes.
 The
 .Fa handle

-is a file descriptor (int) referencing the node to monitor, and 
+is a file descriptor (int) referencing the node to monitor, and

 the
 .Fa mask
 may be one or more of the following:
 the
 .Fa mask
 may be one or more of the following:


@@ -413,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
 .It \(bu DISPATCH_VNODE_REVOKE

-Access to the referenced node was revoked via 
+Access to the referenced node was revoked via

 .Xr revoke 2
 or the underlying fileystem was unmounted.
 .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


@@ -445,7 +575,7 @@ is unused and should be zero.
 .Pp
 Users of this source type are strongly encouraged to perform non-blocking I/O
 and handle any truncated reads or error conditions that may occur. See
 .Pp
 Users of this source type are strongly encouraged to perform non-blocking I/O
 and handle any truncated reads or error conditions that may occur. See

-.Xr fnctl 2
+.Xr fcntl 2

 for additional information about setting the
 .Vt O_NONBLOCK
 flag on a file descriptor.
 for additional information about setting the
 .Vt O_NONBLOCK
 flag on a file descriptor.