Abstraction for interacting with the underlying I/O pipeline.
A PushListener
provide a method, listen
, to expose a server on the the
given SocketAddress.
A PushListener
provide a method, listen
, to expose a server on the the
given SocketAddress. sessionBuilder
is called for each new connection.
It is furnished with a typed PushChannelHandle representing this connection
and expects a PushSession to be returned asynchronously, at which point
the session will begin to receive events. The returned ListeningServer
is used to inspect the server and to shut it down.
Representation of a push-based protocol session.
Representation of a push-based protocol session.
The PushSession is intended to be used with the PushChannelHandle
abstraction to provide the interface for building a push-based protocol
implementation. In this pattern, events coming from the socket are
'pushed' into the session via the receive
method with well defined
thread behavior. Specifically, the receive
method will be called with
new events from the single-threaded Executor
available in the
associated PushChannelHandle. This provides two key benefits for push-based
protocol implementations:
- We remove the overhead of the Future
abstraction intrinsic to the
Transport
and Dispatcher
based model.
- The session itself provides a clear pattern for managing synchronization
that works well with the Promise
abstraction by avoiding explicit
synchronization.
Base type for building a com.twitter.finagle.client.StackClient using the push-based protocol tools.
Implementation of ListeningStackServer which uses the push-based abstractions.
PushSessionTransporters attempt to construct a PushChannelHandle
and provide it to the factory function, returning any errors as
failed Future
s.
PushSessionTransporters attempt to construct a PushChannelHandle
and provide it to the factory function, returning any errors as
failed Future
s.
There is one PushTransporter assigned per remote peer.
Proxy PushSession which can update the underlying session.
Proxy PushSession which can update the underlying session.
Thread safety considerations
- receive
is only intended to be called from within the serial executor, which is
a general rule in all PushSession
implementations.
- updateRef
should be called only from within the handle's serial executor. This
is to avoid race conditions between closing the underlying session (which happens
in the serial executor) and replacing it with a new session: if replacing happens
in the same thread, there is no need to worry about broadcasting close events
from the old session to the new one.
- close
and status
are safe to call from any thread.
Abstraction for interacting with the underlying I/O pipeline.
The
ChannelHandle
provides tools for writing messages to the peer, anExecutor
which provides single threaded behavior for executed tasks, and information about the peer and state of the pipeline.All method calls on the
ChannelHandle
are guaranteed not to result in re-entrance into the PushSession so long as these methods are called from within theserialExecutor
. Specifically, if a session invokes a method on the handle it will not result in a new event reaching the session before the method call has returned. This avoids situations such as a session performing a write and before the call returns a new inbound message arrives and mutates session state in an unexpected way.All failures are fatal to the PushChannelHandle including write failures. Specifically, any failure results in the
onClose
promise being completed with the exception in theThrow
pathway and the underlying socket will be closed.