+Asynchronous Execution +---------------------- + +In certain cases, it's desirable for a node to indicate that it cannot +return any tuple immediately but may be able to do at a later time. This +might either because the node is waiting on an event external to the +database system, such as a ForeignScan awaiting network I/O, or because +the node is waiting for an event internal to the database system - e.g. +one process involved in a parallel query may find that it cannot progress +a certain parallel operation until some other process reaches a certain +point in the computation. A process which discovers this type of situation +can always handle it simply by blocking, but this may waste time that could +be spent executing some other part of the plan where progress could be +made immediately. This is particularly likely to occur when the plan +contains an Append node. + +To use asynchronous execution, a node must first request a tuple from an +async-capable child node using ExecAsyncRequest. Next, it must execute +the asynchronous event loop using ExecAsyncEventLoop; it can avoid giving +up control indefinitely by passing a timeout to this function, even passing +-1 to poll for events without blocking. Eventually, when a node to which an +asynchronous request has been made produces a tuple, the requesting node +will receive a callback from the event loop via ExecAsyncResponse. Typically, +the ExecAsyncResponse callback is the only one required for nodes that wish +to request tuples asynchronously. + +On the other hand, nodes that wish to produce tuples asynchronously +generally need to implement three methods: + +1. When an asynchronous request is made, the node's ExecAsyncRequest callback +will be invoked; it should use ExecAsyncSetRequiredEvents to indicate the +number of file descriptor events for which it wishes to wait and whether it +wishes to receive a callback when the process latch is set. Alternatively, +it can instead use ExecAsyncRequestDone if a result is available immediately. + +2. When the event loop wishes to wait or poll for file descriptor events and +the process latch, the ExecAsyncConfigureWait callback is invoked to configure +the file descriptor wait events for which the node wishes to wait. This +callback isn't needed if the node only cares about the process latch. + +3. When file descriptors or the process latch become ready, the node's +ExecAsyncNotify callback is invoked.