DispatchSource Class

  • Reference

Definition

Namespace:
CoreFoundation
Assembly:
Xamarin.iOS.dll
Assembly:
Xamarin.Mac.dll

DispatchSource is a base class used to reprenset event sources that can monitor a variety of system objects and events including file descriptors, mach ports, processes, virtual filesystem nodes, signal delivery and timers.

public class DispatchSource : CoreFoundation.DispatchObject
type DispatchSource = class
    inherit DispatchObject
Inheritance
Object
DispatchObject
DispatchSource
Inheritance
Object
NativeObject
DispatchObject
DispatchSource
Derived

Remarks

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.  To monitor a specific kind of source, you create an instance of one of the DispatchSource subclasses:

When a state change occurs, the dispatch source will submit its event handler block to its target queue.

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 Resume() before any events will be delivered.

Source Event Handlers

To receive events from the dispatch source, an event handler should be specified via SetEventHandler(Action). The event handler is submitted to the source's target queue when the state 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 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.

Dispatch sources may be suspended or resumed independently of their target queues using Suspend() and Resume() on the dispatch source directly. The data describing events which occur while a source is suspended are coalesced and delivered once the source is resumed.

The handler does not need to be reentrant safe, as it is not resubmitted to the target queue until any prior invocation for that dispatch source has completed.

To unset the event handler, call SetEventHandler(Action) pass null as an argument.

Registration

When 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.

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 SetRegistrationHandler(Action).

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.

Cancellation

The 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). 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.)

The IsCanceled function may be used to determine whether the specified source has been canceled.

When a dispatch source is canceled its optional cancellation handler will be submitted to its target queue. The cancellation handler may be specified via SetCancelHandler(Action). This cancellation handler is invoked only once, and only as a direct consequence of calling Cancel().

Important: 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 closed descriptor while the source's event handler is still running, the event handler may read/write data to the wrong descriptor.

Properties

Handle (Inherited from DispatchObject)
IsCanceled

Determine whether the specified source has been canceled.

Methods

Activate() (Inherited from DispatchObject)
Cancel()

Asynchronously cancels the dispatch source.
Check()
Obsolete.
(Inherited from DispatchObject)
Dispose() (Inherited from DispatchObject)
Dispose(Boolean)

Releases the resources used by the DispatchSource object.
Equals(Object) (Inherited from DispatchObject)
GetHashCode()

Returns the hashcode for this object

(Inherited from DispatchObject)
InitializeHandle(IntPtr) (Inherited from NativeObject)
Release() (Inherited from DispatchObject)
Resume()

Resumes the dispatch source.
Retain() (Inherited from DispatchObject)
SetCancelHandler(Action)

Provides a cancellation handler
SetEventHandler(Action)

Specified a handler to execute when events are received on the dispatch source.
SetRegistrationHandler(Action)

Provides a registration handler
SetTargetQueue(DispatchQueue) (Inherited from DispatchObject)
Suspend()

Suspends the dispatch source.

Applies to