class PortDispatcher

PortObserver lifetime and locking notes.

PortDispatcher is responsible for destroying PortObservers (MaybeReap

or on_zero_handles), however, their destruction may be initiated by

either Dispatcher or PortDispatcher.

PortObservers can exist on up to two doubly linked lists:

- PortObserver::List on PortDispatcher

- DoublyLinkedList

<SignalObserver

*> on Dispatcher

The diagrams below show the *relevant* pointers on different

states of the system. The pure header view is really the

union of all these pointer which can be confusing.

rc = ref counted

p = raw pointer

o = owning pointer

1) Situation after object_wait_async(port, handle) is issued:

list +--------+

+------p------+ +----p-----+ Port |

| v v | |

+-------+--+ +-----------+ +-+------+

| object | | Port | ^

| |

<

--p---+ Observer | |

+----------+ | +---rc----+

| |

+-----------+

| Port |

| Packet |

+-----------+

State changes of the object are propagated from the object

to the port via |p| --> observer --> |rc| calls.

2) Situation after the packet is queued on signal match or the wait

is canceled through the Dispatcher.

+--------+

| Port |

| |

+----------+ +-----------+ +-+---+--+

| object | | Port | ^ |

| | | Observer | | |

+----------+ | +---rc----+ |

+---> | | |

| +-----------+ | list

| | Port | |

+-rc--| Packet |

<

-----o-----+

+-----------+

Note that the object no longer has a |p| to the observer

but the observer still owns the port via |rc|.

The |o| pointer is used to destroy the port observer only

when cancellation happens and the port still owns the packet.

The PortObserver's raw pointer to the Dispatcher is a weak reference

guarded by the port's lock. It is cleared either in MaybeReap or

in PortDispatcher::on_zero_handles.

Cancelation ordering

Observers can be canceled by way of the object or the port. Observers are

canceled by the object when the object's handle count reaches zero and when

waits are canceled by port_cancel. In this path the Dispatcher's lock is

acquired first and the observer is removed from the Dispatcher's observer

list, then the PortDispatcher lock is acquired and the observer is removed

from the PortDispatcher's observer list and may be cleaned up.

When an observer is canceled through the port by way of port_cancel_key there

is a lock ordering issue. The PortDispatcher lock must be held to iterate

over pending observers but the locks for Dispatchers associated with these

observers cannot be acquired while holding the PortDispatcher lock. In this

case, the PortDispatcher first cancels each pending observer with the

PortDispatcher lock held by assigning the observer's packet's type to a

sentinel value and removing them from the PortDispatcher's list to a

temporary list. Then the PortDispatcher lock is released and the observers

are deregistered from their Dispatchers (acquiring the Dispatcher lock) one

at a time. If an observer fires in this state and attempts to queue a

packet PortDispatcher will check the type field and not queue the packet.

Locking

The PortDispatcher's lock guards PortDispatcher's list of observers, the

PortObserver's reference to its Dispatcher, and the packet type field on the

PortObserver's stored zx_port_packet_t in pending observers. The

PortDispatcher lock can be acquired while holding the Dispatcher's lock.

The Dispatcher's lock guards the Dispatcher's list of observers and the

other fields on PortObserver, most notably the packet itself. The

dispatcher lock cannot be acquired while holding the PortDispatcher lock.

Both the PortDispatcher and Dispatcher locks are held when delivering a

packet and when deciding whether to destroy it in MaybeReap.