class Dispatcher
Defined at line 97 of file ../../zircon/kernel/object/include/object/dispatcher.h
Base class for all kernel objects that can be exposed to user-mode via
the syscall API and referenced by handles.
It implements RefCounted because handles are abstractions to a multiple
references from user mode or kernel mode that control the lifetime of
the object.
It implements Recyclable because upon final Release() on the RefPtr
it might be necessary to implement a destruction pattern that avoids
deep recursion since the kernel stack is very limited.
You don't derive directly from this class; instead derive
from SoloDispatcher or PeeredDispatcher.
Public Methods
void ~Dispatcher ()Dispatchers are either Solo or Peered. They handle refcounting
and locking differently.
Defined at line 64 of file ../../zircon/kernel/object/dispatcher.cc
zx_status_t AddObserver (SignalObserver * observer, const void * handle, zx_signals_t signals, TriggerMode trigger_mode)Add a observer which will be triggered when any |signal| becomes active
or cancelled when |handle| is destroyed.
|observer| must be non-null, and |is_waitable| must report true.
Be sure to |RemoveObserver| before the Dispatcher is destroyed.
If |trigger_mode| is set to Edge, the signal state is not checked
on entry and the observer is only triggered if a signal subsequently
becomes active.
Defined at line 78 of file ../../zircon/kernel/object/dispatcher.cc
bool RemoveObserver (SignalObserver * observer, zx_signals_t * signals)Remove an observer.
Returns true if the method removed |observer|, otherwise returns false. If
provided, |signals| will be given the current state of the dispatcher's
signals when the observer was removed.
This method may return false if the observer was never added or has already been removed in
preparation for its destruction.
It is an error to call this method with an observer that's observing some other Dispatcher.
May only be called when |is_waitable| reports true.
Defined at line 107 of file ../../zircon/kernel/object/dispatcher.cc
zx_koid_t get_koid ()Defined at line 109 of file ../../zircon/kernel/object/include/object/dispatcher.h
void increment_handle_count ()Defined at line 111 of file ../../zircon/kernel/object/include/object/dispatcher.h
bool decrement_handle_count ()Returns true exactly when the handle count goes to zero.
Defined at line 119 of file ../../zircon/kernel/object/include/object/dispatcher.h
void Cancel (const void * handle)Cancel observers of this object's state (e.g., waits on the object).
Should be called when a handle to this dispatcher is being destroyed.
May only be called when |is_waitable| reports true.
Defined at line 127 of file ../../zircon/kernel/object/dispatcher.cc
uint32_t current_handle_count ()Defined at line 131 of file ../../zircon/kernel/object/include/object/dispatcher.h
bool CancelByKey (const void * handle, const void * port, uint64_t key)Like Cancel() but issued via zx_port_cancel().
Returns true if an observer was canceled.
May only be called when |is_waitable| reports true.
Defined at line 150 of file ../../zircon/kernel/object/dispatcher.cc
zx_status_t get_name (char (&)[32] out_name)get_name() will return a null-terminated name of ZX_MAX_NAME_LEN - 1 or fewer
characters in |out_name|.
Returns ZX_ERR_WRONG_TYPE for object types that don't have ZX_PROP_NAME.
Defined at line 200 of file ../../zircon/kernel/object/include/object/dispatcher.h
zx_obj_type_t get_type ()Interface for derived classes.
zx_status_t user_signal_self (uint32_t clear_mask, uint32_t set_mask)zx_status_t user_signal_peer (uint32_t clear_mask, uint32_t set_mask)zx_koid_t get_related_koid ()bool is_waitable ()zx_signals_t PollSignals ()Poll the currently active signals on this object.
By the time the result of the function is inspected, the signals may have already
changed. Typically should only be used for tests or logging.
Defined at line 228 of file ../../zircon/kernel/object/dispatcher.cc
zx_info_handle_basic_t GetHandleInfo (zx_rights_t rights)Returns the information for zx_object_get_info(ZX_INFO_HANDLE_BASIC,..).
Defined at line 233 of file ../../zircon/kernel/object/dispatcher.cc
void on_zero_handles ()Defined at line 192 of file ../../zircon/kernel/object/include/object/dispatcher.h
zx_status_t set_name (const char * name, size_t len)set_name() will truncate to ZX_MAX_NAME_LEN - 1 and ensure there is a
terminating null.
Returns ZX_ERR_WRONG_TYPE for object types that don't have ZX_PROP_NAME.
Defined at line 207 of file ../../zircon/kernel/object/include/object/dispatcher.h
void set_owner (zx_koid_t new_owner)Called whenever the object is bound to a new process. The |new_owner| is
the koid of the new process. It is only overridden for objects where a single
owner makes sense.
Defined at line 220 of file ../../zircon/kernel/object/include/object/dispatcher.h
Protected Methods
void ClearSignals (zx_signals_t signals)Clear the signals specified by |signals|.
Defined at line 250 of file ../../zircon/kernel/object/include/object/dispatcher.h
zx_signals_t RaiseSignalsLocked (zx_signals_t signals)Raise (set) signals specified by |signals| without notifying observers.
Returns the old value.
Defined at line 257 of file ../../zircon/kernel/object/include/object/dispatcher.h
zx_signals_t GetSignalsStateLocked ()Returns the stored signal state.
Defined at line 267 of file ../../zircon/kernel/object/include/object/dispatcher.h
void Dispatcher (zx_signals_t signals)At construction, the object is asserting |signals|.
Defined at line 59 of file ../../zircon/kernel/object/dispatcher.cc
void UpdateState (zx_signals_t clear, zx_signals_t set, zx_signals_t strobe)Update this object's signal state and notify matching observers.
Clear the signals specified by |clear|, set the signals specified by |set|, then invoke each
observer that's waiting on one or more of the signals in |set| or |strobe|.
Note, clearing a signal or setting a signal that was already set will not cause an observer to
be notified.
May only be called when |is_waitable| reports true.
Defined at line 177 of file ../../zircon/kernel/object/dispatcher.cc
void UpdateStateLocked (zx_signals_t clear, zx_signals_t set, zx_signals_t strobe)Defined at line 206 of file ../../zircon/kernel/object/dispatcher.cc
void NotifyObserversLocked (zx_signals_t signals, OwnedWaitQueue * queue_to_own)Notify the observers waiting on one or more |signals|.
unlike UpdateState and UpdateStateLocked, this method does not modify the stored signal state.
Defined at line 191 of file ../../zircon/kernel/object/dispatcher.cc
Lock<CriticalMutex> * get_lock ()This lock protects most, but not all, of Dispatcher's state as well as some of the state of
types derived from Dispatcher.
One purpose of this lock is to maintain the following |observers_| and |signals_| invariant:
* When not held, there must be no |observers_| matching any of the active |signals_|.
Note, there is one operation on |signals_| that may be performed without holding this lock,
clearing (i.e. deasserting) signals. See the comment at |signals_|.
Enumerations
enum TriggerMode| Name | Value |
|---|---|
| Level | 0 |
| Edge | 1 |
Defined at line 140 of file ../../zircon/kernel/object/include/object/dispatcher.h
Records
Friends
class Recyclable