A Pipelined PushSession.
Abstraction for interacting with the underlying I/O pipeline.
Abstraction for interacting with the underlying I/O pipeline.
The ChannelHandle
provides tools for writing messages to the peer, an Executor
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 the serialExecutor
.
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 the
Throw
pathway and the underlying socket will be closed.
Base proxy implementation for PushChannelHandle
Base proxy implementation for PushChannelHandle
Implementations should override methods as appropriate.
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. See the README.md
for more details.
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.
A Pipelined PushSession.
This assumes servers will respect normal pipelining semantics, and that replies will be sent in the same order as requests were sent.
Because many requests might be sharing the same push channel, Futures returned by PipeliningClientPushSession#apply are masked, and will only propagate the interrupt if the Future doesn't return after a configurable amount of time after the interruption. This ensures that interrupting a Future in one request won't change the result of another request unless the connection is stuck, and does not look like it will make progress. Use
stallTimeout
to configure this timeout.