Safe Haskell	None
Language	Haskell2010

Ouroboros.Network.ConnectionManager.Types

Contents

Connection manager core types
Connection Manager
Exceptions
Counters
Mux types
Promise
Tracing

Description

Connection manager core types.

Connection manager is responsible for managing uni- and bi-directional connections and threads which are running network applications using 'network-mux'. In particular it is responsible for:

opening new connection / reusing connections (for bidirectional connections) and exposes a method to register inbound connections;
run connection handler, i.e. ConnectionHandler, which runs handshake negotiation, notifies connection manager on the results and starts the multiplexer;
error handling for connection threads;
keeping track of handshake negotiation: whether a unidirectional or duplex connection was negotiated;
tracking state of each connection;
keep inbound connections under limits.

Connection manager is designed to work for any Mode, though the most useful ones are ResponderMode and InitiatorResponderMode:

InitiatorResponderMode - useful for node-to-node applications, which needs to create outbound connections as well as accept inbound ones;
ResponderMode - useful for server side of node-to-client; it allows us to share the same server between node-to-client and node-to-node;
InitiatorMode - could be used on client side of node-to-client applications.

The calls acquireOutboundConnection and includeInboundConnection return once a connection has been negotiated. The returned handle contains all the information that is needed to start and monitor mini-protocols through the mux interface.

For inbound connections, the connection manager will pass handle (also after negotiation).

┌────────────────────────┐
│                        │        ┏━━━━━━━━━━━━━━━━┓
│   ConnectionHandler    │        ┃                ┃
│                        ┝━━━━━━━▶┃     handle     ┃
│  inbound / outbound    │        ┃                ┃
│         ┃              │        ┗━━┳━━━━━━━━━━━━━┛
└─────────╂──────────────┘           ┃
          ┃                          ┃
          ▼                          ┃
   ┏━━━━━━━━━━━━━━━━━┓               ┃
   ┃ Control Channel ┃               ┃
   ┗━━━━━━┳━━━━━━━━━━┛               ┃
          ┃                          ┃
          ┃                          ┃
          ▼                          ┃
┌────────────────────────┐           ┃
│                        │           ┃
│         Server         │◀━━━━━━━━━━┛
│                        │
└────────────────────────┘

Termination procedure as well as connection state machine is not described in this haddock, see associated specification.

The handle is used in `ouroboros-network` package to construct PeerStateActions which allow for the outbound governor to

Synopsis

data AddressType
- = IPv4Address
- | IPv6Address
data Provenance
- = Inbound
- | Outbound
data DataFlow
- = Unidirectional
- | Duplex
data TimeoutExpired
- = Expired
- | Ticking
data ConnectionType
- = UnnegotiatedConn !Provenance
- | InboundIdleConn !DataFlow
- | OutboundIdleConn !DataFlow
- | NegotiatedConn !Provenance !DataFlow
- | DuplexConn
newtype MaskedAction (m :: Type -> Type) a = MaskedAction {
- runWithUnmask :: (forall x. m x -> m x) -> m a
}
type ConnectionHandlerFn handlerTrace socket peerAddr handle handleError version (m :: Type -> Type) = socket -> PromiseWriter m (Either handleError (HandshakeConnectionResult handle version)) -> Tracer m handlerTrace -> ConnectionId peerAddr -> (DiffTime -> socket -> m (Bearer m)) -> MaskedAction m ()
newtype ConnectionHandler (muxMode :: Mode) handlerTrace socket peerAddr handle handleError version (m :: Type -> Type) = ConnectionHandler {
- connectionHandler :: WithMuxTuple muxMode (ConnectionHandlerFn handlerTrace socket peerAddr handle handleError version m)
}
data Inactive
- = Active MiniProtocolDir
- | Inactive
data ExceptionInHandler where
- ExceptionInHandler :: forall peerAddr. (Typeable peerAddr, Show peerAddr) => !peerAddr -> !SomeException -> ExceptionInHandler
data HandleErrorType
- = HandshakeFailure
- | HandshakeProtocolViolation
data HandshakeConnectionResult handle version
- = HandshakeConnectionQuery
- | HandshakeConnectionResult handle version
type PrunePolicy peerAddr = StdGen -> Map peerAddr ConnectionType -> Int -> Set peerAddr
simplePrunePolicy :: Ord peerAddr => PrunePolicy peerAddr
data ConnectionManager (muxMode :: Mode) socket peerAddr handle handleError (m :: Type -> Type) = ConnectionManager {
- getConnectionManager :: WithMuxMode muxMode (OutboundConnectionManager muxMode socket peerAddr handle handleError m) (InboundConnectionManager muxMode socket peerAddr handle handleError m)
- readState :: STM m (Map peerAddr AbstractState)
- waitForOutboundDemotion :: peerAddr -> STM m ()
}
data Connected peerAddr handle handleError
- = Connected !(ConnectionId peerAddr) !DataFlow !handle
- | Disconnected !(ConnectionId peerAddr) !(Maybe handleError)
data OperationResult a
- = UnsupportedState !AbstractState
- | OperationSuccess !a
- | TerminatedConnection !AbstractState
resultInState :: OperationResult AbstractState -> AbstractState
data DemotedToColdRemoteTr
- = CommitTr
- | KeepTr
type AcquireOutboundConnection peerAddr handle handleError (m :: Type -> Type) = peerAddr -> m (Connected peerAddr handle handleError)
type IncludeInboundConnection socket peerAddr handle handleError (m :: Type -> Type) = Word32 -> socket -> peerAddr -> m (Connected peerAddr handle handleError)
acquireOutboundConnection :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasInitiator muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> AcquireOutboundConnection peerAddr handle handleError m
promotedToWarmRemote :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasResponder muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> peerAddr -> m (OperationResult AbstractState)
demotedToColdRemote :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasResponder muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> peerAddr -> m (OperationResult AbstractState)
releaseOutboundConnection :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasInitiator muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> peerAddr -> m (OperationResult AbstractState)
includeInboundConnection :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasResponder muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> IncludeInboundConnection socket peerAddr handle handleError m
releaseInboundConnection :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasResponder muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> peerAddr -> m (OperationResult DemotedToColdRemoteTr)
numberOfConnections :: forall (muxMode :: Mode) socket peerAddr handle handleError (m :: Type -> Type). HasResponder muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> STM m Int
data OutboundConnectionManager (muxMode :: Mode) socket peerAddr handle handleError (m :: Type -> Type) where
- OutboundConnectionManager :: forall (muxMode :: Mode) peerAddr handle handleError (m :: Type -> Type) socket. HasInitiator muxMode ~ 'True => {..} -> OutboundConnectionManager muxMode socket peerAddr handle handleError m
data InboundConnectionManager (muxMode :: Mode) socket peerAddr handle handleError (m :: Type -> Type) where
- InboundConnectionManager :: forall (muxMode :: Mode) socket peerAddr handle handleError (m :: Type -> Type). HasResponder muxMode ~ 'True => {..} -> InboundConnectionManager muxMode socket peerAddr handle handleError m
data ConnectionManagerError peerAddr
- = ConnectionExists !Provenance !peerAddr !CallStack
- | ForbiddenConnection !(ConnectionId peerAddr) !CallStack
- | ImpossibleConnection !(ConnectionId peerAddr) !CallStack
- | ConnectionTerminating !(ConnectionId peerAddr) !CallStack
- | ConnectionTerminated !peerAddr !CallStack
- | ImpossibleState !peerAddr !CallStack
- | ForbiddenOperation !peerAddr !AbstractState !CallStack
- | UnknownPeer !peerAddr !CallStack
data SomeConnectionManagerError = (Typeable addr, Show addr) => SomeConnectionManagerError !(ConnectionManagerError addr)
data AbstractState
- = UnknownConnectionSt
- | ReservedOutboundSt
- | UnnegotiatedSt !Provenance
- | InboundIdleSt !DataFlow
- | InboundSt !DataFlow
- | OutboundUniSt
- | OutboundDupSt !TimeoutExpired
- | OutboundIdleSt !DataFlow
- | DuplexSt
- | WaitRemoteIdleSt
- | TerminatingSt
- | TerminatedSt
data ConnectionManagerCounters = ConnectionManagerCounters {
- fullDuplexConns :: !Int
- duplexConns :: !Int
- unidirectionalConns :: !Int
- inboundConns :: !Int
- outboundConns :: !Int
}
data WithMuxMode (mode :: Mode) a b where
- WithInitiatorMode :: forall a b. a -> WithMuxMode 'InitiatorMode a b
- WithResponderMode :: forall b a. b -> WithMuxMode 'ResponderMode a b
- WithInitiatorResponderMode :: forall a b. a -> b -> WithMuxMode 'InitiatorResponderMode a b
withInitiatorMode :: forall (mode :: Mode) a b. HasInitiator mode ~ 'True => WithMuxMode mode a b -> a
withResponderMode :: forall (mode :: Mode) a b. HasResponder mode ~ 'True => WithMuxMode mode a b -> b
newEmptyPromiseIO :: (MonadSTM m, MonadThrow (STM m)) => m (PromiseReader m a, PromiseWriter m a)
newtype PromiseReader (m :: Type -> Type) a = PromiseReader {
- readPromise :: STM m a
}
readPromiseIO :: MonadSTM m => PromiseReader m a -> m a
data PromiseWriter (m :: Type -> Type) a = PromiseWriter {
- writePromise :: a -> STM m ()
- forcePromise :: a -> STM m ()
}
data PromiseWriterException = PromiseWriterBlocked
data AssertionLocation peerAddr
- = ReleaseInboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
- | AcquireOutboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
- | ReleaseOutboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
- | PromotedToWarmRemote !(Maybe (ConnectionId peerAddr)) !AbstractState
- | DemotedToColdRemote !(Maybe (ConnectionId peerAddr)) !AbstractState
data MaybeUnknown state
- = Known !state
- | Race !state
- | Unknown
data Transition' state = Transition {
- fromState :: !state
- toState :: !state
}
type Transition state = Transition' (MaybeUnknown state)
type AbstractTransition = Transition' AbstractState
mkTransition :: state -> state -> Transition state
mkAbsTransition :: AbstractState -> AbstractState -> AbstractTransition
type TransitionTrace peerAddr state = TransitionTrace' peerAddr (MaybeUnknown state)
data TransitionTrace' peerAddr state = TransitionTrace {
- ttPeerAddr :: peerAddr
- ttTransition :: Transition' state
}
type AbstractTransitionTrace peerAddr = TransitionTrace' peerAddr AbstractState

Connection manager core types

Connection Types

data AddressType Source #

Connection manager supports IPv4 and IPv6 addresses.

Constructors

IPv4Address
IPv6Address

Instances

Instances details

Show AddressType Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> AddressType -> ShowS # show :: AddressType -> String # showList :: [AddressType] -> ShowS #

data Provenance Source #

Each connection is is either initiated locally (outbound) or by a remote peer (inbound).

Constructors

Inbound	An inbound connection: one that was initiated by a remote peer.
Outbound	An outbound connection: one that was initiated by us.

Instances

Instances details

Show Provenance Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> Provenance -> ShowS # show :: Provenance -> String # showList :: [Provenance] -> ShowS #
Eq Provenance Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) :: Provenance -> Provenance -> Bool # (/=) :: Provenance -> Provenance -> Bool #
Ord Provenance Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare :: Provenance -> Provenance -> Ordering # (<) :: Provenance -> Provenance -> Bool # (<=) :: Provenance -> Provenance -> Bool # (>) :: Provenance -> Provenance -> Bool # (>=) :: Provenance -> Provenance -> Bool # max :: Provenance -> Provenance -> Provenance # min :: Provenance -> Provenance -> Provenance #

data DataFlow Source #

Each connection negotiates if it is uni- or bi-directional. DataFlow is a life time property of a connection, once negotiated it never changes.

NOTE: This type is isomorphic to DiffusionMode for `node-to-node` connections (see ntnDataFlow), but it isn't for `node-to-client` connections (see `Ouroboros.Network.Diffusion.P2P.ntcDataFlow).

Constructors

Unidirectional
Duplex

Instances

Instances details

Show DataFlow Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> DataFlow -> ShowS # show :: DataFlow -> String # showList :: [DataFlow] -> ShowS #
Eq DataFlow Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) :: DataFlow -> DataFlow -> Bool # (/=) :: DataFlow -> DataFlow -> Bool #
Ord DataFlow Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare :: DataFlow -> DataFlow -> Ordering # (<) :: DataFlow -> DataFlow -> Bool # (<=) :: DataFlow -> DataFlow -> Bool # (>) :: DataFlow -> DataFlow -> Bool # (>=) :: DataFlow -> DataFlow -> Bool # max :: DataFlow -> DataFlow -> DataFlow # min :: DataFlow -> DataFlow -> DataFlow #

data TimeoutExpired Source #

Boolean like type which indicates if the timeout on OutboundStateDuplex has expired.

Constructors

Expired
Ticking

Instances

Instances details

Show TimeoutExpired Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> TimeoutExpired -> ShowS # show :: TimeoutExpired -> String # showList :: [TimeoutExpired] -> ShowS #
Eq TimeoutExpired Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) :: TimeoutExpired -> TimeoutExpired -> Bool # (/=) :: TimeoutExpired -> TimeoutExpired -> Bool #
Ord TimeoutExpired Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare :: TimeoutExpired -> TimeoutExpired -> Ordering # (<) :: TimeoutExpired -> TimeoutExpired -> Bool # (<=) :: TimeoutExpired -> TimeoutExpired -> Bool # (>) :: TimeoutExpired -> TimeoutExpired -> Bool # (>=) :: TimeoutExpired -> TimeoutExpired -> Bool # max :: TimeoutExpired -> TimeoutExpired -> TimeoutExpired # min :: TimeoutExpired -> TimeoutExpired -> TimeoutExpired #

data ConnectionType Source #

Either unnegotiated or negotiated unidirectional or duplex connections. This is not a static property of a connection. It is used by PrunePolicy.

Note: the order matters, it can be used by a PickPolicy, e.g. simplePickPolicy.

Constructors

UnnegotiatedConn !Provenance	An unnegotiated connection.
InboundIdleConn !DataFlow	An inbound idle connection.
OutboundIdleConn !DataFlow	An outbound idle connection.
NegotiatedConn !Provenance !DataFlow	A negotiated connection, which is used in only one direction indicated by `Provenance`. The connection could itself negotiated either `Duplex` or `Unidirectional` data flow.
DuplexConn	A connection which is running in full duplex mode.

Instances

Instances details

Show ConnectionType Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> ConnectionType -> ShowS # show :: ConnectionType -> String # showList :: [ConnectionType] -> ShowS #
Eq ConnectionType Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) :: ConnectionType -> ConnectionType -> Bool # (/=) :: ConnectionType -> ConnectionType -> Bool #
Ord ConnectionType Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare :: ConnectionType -> ConnectionType -> Ordering # (<) :: ConnectionType -> ConnectionType -> Bool # (<=) :: ConnectionType -> ConnectionType -> Bool # (>) :: ConnectionType -> ConnectionType -> Bool # (>=) :: ConnectionType -> ConnectionType -> Bool # max :: ConnectionType -> ConnectionType -> ConnectionType # min :: ConnectionType -> ConnectionType -> ConnectionType #

Connection Handler

ConnectionHandler provides monadic action which runs handshake negotiation and starts the multiplexer. It's the component which has access to underlying socket. There's one-to-one correspondence between sockets and threads that run the handler.

ConnectionHandlerFn: is the type of callback executed for each connection. All arguments are provided by the connection manager.
ConnectionHandler: is a newtype wrapper which provides inbound / outbound handlers depending on Mode.

newtype MaskedAction (m :: Type -> Type) a Source #

Handler action is started with asynchronous exceptions masked; this allows to install exception handlers in an async-safe way.

Constructors

MaskedAction
Fields runWithUnmask :: (forall x. m x -> m x) -> m a

type ConnectionHandlerFn handlerTrace socket peerAddr handle handleError version (m :: Type -> Type) = socket -> PromiseWriter m (Either handleError (HandshakeConnectionResult handle version)) -> Tracer m handlerTrace -> ConnectionId peerAddr -> (DiffTime -> socket -> m (Bearer m)) -> MaskedAction m () Source #

MaskedAction which is executed by thread designated for a given connection.

PromiseWriter allows to notify the ConnectionManager about the result of handshake negotiation.

Note: PromiseWriter could be replaced with an stm action which is accessing the TVar which holds state of the connection.

newtype ConnectionHandler (muxMode :: Mode) handlerTrace socket peerAddr handle handleError version (m :: Type -> Type) Source #

Connection handler action. It is index by muxMode :: Mode. There's one ConnectionHandlerFn per provenance, possibly limited by muxMode.

Constructors

ConnectionHandler
Fields connectionHandler :: WithMuxTuple muxMode (ConnectionHandlerFn handlerTrace socket peerAddr handle handleError version m) Connection handler.

data Inactive Source #

Boolean like type

Constructors

Active MiniProtocolDir
Inactive

Instances

Instances details

Show Inactive Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> Inactive -> ShowS # show :: Inactive -> String # showList :: [Inactive] -> ShowS #
Eq Inactive Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) :: Inactive -> Inactive -> Bool # (/=) :: Inactive -> Inactive -> Bool #

data ExceptionInHandler where Source #

Exception which where caught in the connection thread and were re-thrown in the main thread by the rethrowPolicy.

Constructors

ExceptionInHandler :: forall peerAddr. (Typeable peerAddr, Show peerAddr) => !peerAddr -> !SomeException -> ExceptionInHandler

Instances

Instances details

Exception ExceptionInHandler Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods toException :: ExceptionInHandler -> SomeException # fromException :: SomeException -> Maybe ExceptionInHandler # displayException :: ExceptionInHandler -> String # backtraceDesired :: ExceptionInHandler -> Bool #
Show ExceptionInHandler Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> ExceptionInHandler -> ShowS # show :: ExceptionInHandler -> String # showList :: [ExceptionInHandler] -> ShowS #

data HandleErrorType Source #

Data type used to classify handleErrors.

Constructors

HandshakeFailure	Handshake negotiation failed. This is not a protocol error.
HandshakeProtocolViolation	Handshake protocol error. This should include timeout errors or any IO errors.

data HandshakeConnectionResult handle version Source #

Constructors

HandshakeConnectionQuery	Handshake saw a query.
HandshakeConnectionResult handle version	Handshake resulted in a connection and version.

Prune Policy

type PrunePolicy peerAddr = StdGen -> Map peerAddr ConnectionType -> Int -> Set peerAddr Source #

PrunePolicy allows to pick a select peers from which we will disconnect (we use TCP reset). The chosen connections will be terminated by the connection manger once it detects that there are too many inbound connections.

simplePrunePolicy :: Ord peerAddr => PrunePolicy peerAddr Source #

The simplest PrunePolicy, it should only be used for tests.

Connection Manager

Connection Manager Arguments

data ConnectionManager (muxMode :: Mode) socket peerAddr handle handleError (m :: Type -> Type) Source #

ConnectionManager.

We identify resources (e.g. Socket or HANDLE) by their address. It is enough for us to use just the remote address rather than connection identifier, since we need one connection towards that peer, even if we are connected through multiple local addresses. It is safe to share a connection manager with multiple listening sockets.

Constructors

ConnectionManager

Fields

getConnectionManager :: WithMuxMode muxMode (OutboundConnectionManager muxMode socket peerAddr handle handleError m) (InboundConnectionManager muxMode socket peerAddr handle handleError m)
readState :: STM m (Map peerAddr AbstractState)
waitForOutboundDemotion :: peerAddr -> STM m ()
This STM action will block until the given connection is fully closed/terminated. If the connection manager doesn't have any connection to that peer it won't block.

API

data Connected peerAddr handle handleError Source #

Result of acquireOutboundConnection or includeInboundConnection.

Constructors

Connected !(ConnectionId peerAddr) !DataFlow !handle

We are connected and mux is running.

Disconnected !(ConnectionId peerAddr) !(Maybe handleError)

There was an error during handshake negotiation.

Implementation detail: we return Maybe handleError, rather than handleError. In case of an existing inbound connection, the implementation of acquireOutboundConnection is awaiting on handshake through the connection state. The TerminatingState or TerminatedState are not only used for handshake errors, but also for normal termination, hence the Maybe. We could await on update from the handshake instead, but this would introduce a race between inbound / outbound threads.

data OperationResult a Source #

Custom either type for result of various methods.

Constructors

UnsupportedState !AbstractState
OperationSuccess !a
TerminatedConnection !AbstractState

Instances

Instances details

Functor OperationResult Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods fmap :: (a -> b) -> OperationResult a -> OperationResult b # (<$) :: a -> OperationResult b -> OperationResult a #
Show a => Show (OperationResult a) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> OperationResult a -> ShowS # show :: OperationResult a -> String # showList :: [OperationResult a] -> ShowS #

resultInState :: OperationResult AbstractState -> AbstractState Source #

data DemotedToColdRemoteTr Source #

Return value of releaseInboundConnection to inform the caller about the transition.

Constructors

CommitTr	`Commit^{dataFlow}` transition from `InboundIdleState dataFlow`.
KeepTr	Either `DemotedToCold^{Remote}` transition from `DuplexState`, or a level triggered `Awake^{Duplex}_{Local}` transition. In both cases the server must keep the responder side of all protocols ready.

Instances

Instances details

Show DemotedToColdRemoteTr Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> DemotedToColdRemoteTr -> ShowS # show :: DemotedToColdRemoteTr -> String # showList :: [DemotedToColdRemoteTr] -> ShowS #

type AcquireOutboundConnection peerAddr handle handleError (m :: Type -> Type) = peerAddr -> m (Connected peerAddr handle handleError) Source #

type IncludeInboundConnection socket peerAddr handle handleError (m :: Type -> Type) Source #

Arguments

= Word32	inbound connections hard limit. NOTE: Check TODO over at includeInboundConnectionImpl definition.
-> socket
-> peerAddr
-> m (Connected peerAddr handle handleError)

Outbound side

acquireOutboundConnection :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasInitiator muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> AcquireOutboundConnection peerAddr handle handleError m Source #

Include outbound connection into ConnectionManager.

This executes:

$Reserve$ to $Negotiated^{*}_{Outbound}$ transitions
$PromotedToWarm^{Duplex}_{Local}$ transition
$Awake^{Duplex}_{Local}$ transition

promotedToWarmRemote :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasResponder muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> peerAddr -> m (OperationResult AbstractState) Source #

Notify the ConnectionManager that a remote end promoted us to a warm peer.

This executes either:

$PromotedToWarm^{Duplex}_{Remote}$ transition,
$Awake^{*}_{Remote}$ transition

from the specification.

demotedToColdRemote :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasResponder muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> peerAddr -> m (OperationResult AbstractState) Source #

Notify the ConnectionManager that a remote end demoted us to a /cold peer/.

This executes:

$DemotedToCold^{*}_{Remote}$ transition.

This method is idempotent.

releaseOutboundConnection Source #

Arguments

:: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasInitiator muxMode ~ 'True
=> ConnectionManager muxMode socket peerAddr handle handleError m
-> peerAddr
-> m (OperationResult AbstractState)	reports the from-state.

Release outbound connection.

This executes:

$DemotedToCold^{*}_{Local}$ transitions

Inbound side

includeInboundConnection :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasResponder muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> IncludeInboundConnection socket peerAddr handle handleError m Source #

Include an inbound connection into ConnectionManager. This executes:

$Reserve$ to $Negotiated^{*}_{Outbound}$ transitions
$PromotedToWarm^{Duplex}_{Local}$ transition
$Awake^{Duplex}_{Local}$ transition

releaseInboundConnection :: forall (muxMode :: Mode) socket peerAddr handle handleError m. HasResponder muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> peerAddr -> m (OperationResult DemotedToColdRemoteTr) Source #

Release outbound connection. Returns if the operation was successful.

This executes:

$Commit*{*}$ transition
$TimeoutExpired$ transition

numberOfConnections :: forall (muxMode :: Mode) socket peerAddr handle handleError (m :: Type -> Type). HasResponder muxMode ~ 'True => ConnectionManager muxMode socket peerAddr handle handleError m -> STM m Int Source #

Number of connections tracked by the server.

Private API

data OutboundConnectionManager (muxMode :: Mode) socket peerAddr handle handleError (m :: Type -> Type) where Source #

Outbound connection manager API.

Constructors

OutboundConnectionManager
Fields :: forall (muxMode :: Mode) peerAddr handle handleError (m :: Type -> Type) socket. HasInitiator muxMode ~ 'True => { ocmAcquireConnection :: AcquireOutboundConnection peerAddr handle handleError m , ocmReleaseConnection :: peerAddr -> m (OperationResult AbstractState) } -> OutboundConnectionManager muxMode socket peerAddr handle handleError m

data InboundConnectionManager (muxMode :: Mode) socket peerAddr handle handleError (m :: Type -> Type) where Source #

Inbound connection manager API. For a server implementation we also need to know how many connections are now managed by the connection manager.

This type is an internal detail of ConnectionManager

Constructors

InboundConnectionManager

Fields

:: forall (muxMode :: Mode) socket peerAddr handle handleError (m :: Type -> Type). HasResponder muxMode ~ 'True
=> { icmIncludeConnection :: IncludeInboundConnection socket peerAddr handle handleError m
, icmReleaseConnection :: peerAddr -> m (OperationResult DemotedToColdRemoteTr)
, icmPromotedToWarmRemote :: peerAddr -> m (OperationResult AbstractState)
, icmDemotedToColdRemote :: peerAddr -> m (OperationResult AbstractState)
, icmNumberOfConnections :: STM m Int
} -> InboundConnectionManager muxMode socket peerAddr handle handleError m

Exceptions

data ConnectionManagerError peerAddr Source #

Exceptions used by ConnectionManager.

Constructors

ConnectionExists !Provenance !peerAddr !CallStack	A connection manager was asked for an outbound connection and there either exists a connection used in outbound direction or a reservation for an outbound connection.
ForbiddenConnection !(ConnectionId peerAddr) !CallStack	Connection manager was asked for an outbound connection which turned out to be unidirectional inbound, and thus it cannot be re-used..
ImpossibleConnection !(ConnectionId peerAddr) !CallStack	Connections that would be forbidden by the kernel (`TCP` semantics).
ConnectionTerminating !(ConnectionId peerAddr) !CallStack	Connection is now terminating.
ConnectionTerminated !peerAddr !CallStack	Connection has terminated.
ImpossibleState !peerAddr !CallStack	Connection manager in impossible state.
ForbiddenOperation !peerAddr !AbstractState !CallStack	A forbidden operation in the given connection state.
UnknownPeer !peerAddr !CallStack	A connection does not exists. Only thrown when an existing connection was expected.

Instances

Instances details

(Show peerAddr, Typeable peerAddr) => Exception (ConnectionManagerError peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods toException :: ConnectionManagerError peerAddr -> SomeException # fromException :: SomeException -> Maybe (ConnectionManagerError peerAddr) # displayException :: ConnectionManagerError peerAddr -> String # backtraceDesired :: ConnectionManagerError peerAddr -> Bool #
Show peerAddr => Show (ConnectionManagerError peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> ConnectionManagerError peerAddr -> ShowS # show :: ConnectionManagerError peerAddr -> String # showList :: [ConnectionManagerError peerAddr] -> ShowS #

data SomeConnectionManagerError Source #

Existential wrapper for ConnectionManagerError peerAddr. It allows to use fromException, without being bothered about the address type.

Constructors

(Typeable addr, Show addr) => SomeConnectionManagerError !(ConnectionManagerError addr)

Instances

Instances details

Exception SomeConnectionManagerError Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods toException :: SomeConnectionManagerError -> SomeException # fromException :: SomeException -> Maybe SomeConnectionManagerError # displayException :: SomeConnectionManagerError -> String # backtraceDesired :: SomeConnectionManagerError -> Bool #
Show SomeConnectionManagerError Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> SomeConnectionManagerError -> ShowS # show :: SomeConnectionManagerError -> String # showList :: [SomeConnectionManagerError] -> ShowS #

data AbstractState Source #

Useful for tracing and error messages.

Constructors

UnknownConnectionSt	Unknown connection. This state indicates the connection manager removed this connection from its state.
ReservedOutboundSt
UnnegotiatedSt !Provenance
InboundIdleSt !DataFlow
InboundSt !DataFlow
OutboundUniSt
OutboundDupSt !TimeoutExpired
OutboundIdleSt !DataFlow
DuplexSt
WaitRemoteIdleSt
TerminatingSt
TerminatedSt

Instances

Instances details

Show AbstractState Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> AbstractState -> ShowS # show :: AbstractState -> String # showList :: [AbstractState] -> ShowS #
Eq AbstractState Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) :: AbstractState -> AbstractState -> Bool # (/=) :: AbstractState -> AbstractState -> Bool #
Ord AbstractState Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare :: AbstractState -> AbstractState -> Ordering # (<) :: AbstractState -> AbstractState -> Bool # (<=) :: AbstractState -> AbstractState -> Bool # (>) :: AbstractState -> AbstractState -> Bool # (>=) :: AbstractState -> AbstractState -> Bool # max :: AbstractState -> AbstractState -> AbstractState # min :: AbstractState -> AbstractState -> AbstractState #

Counters

data ConnectionManagerCounters Source #

Counters for tracing and analysis purposes

Constructors

ConnectionManagerCounters
Fields fullDuplexConns :: !Int number of full duplex connections duplexConns :: !Int number of negotiated duplex connections (including DuplexState connections) unidirectionalConns :: !Int number of negotiated unidirectional connections inboundConns :: !Int number of inbound connections outboundConns :: !Int number of outbound connections

Instances

Instances details

Monoid ConnectionManagerCounters Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods mempty :: ConnectionManagerCounters # mappend :: ConnectionManagerCounters -> ConnectionManagerCounters -> ConnectionManagerCounters # mconcat :: [ConnectionManagerCounters] -> ConnectionManagerCounters #
Semigroup ConnectionManagerCounters Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (<>) :: ConnectionManagerCounters -> ConnectionManagerCounters -> ConnectionManagerCounters # sconcat :: NonEmpty ConnectionManagerCounters -> ConnectionManagerCounters # stimes :: Integral b => b -> ConnectionManagerCounters -> ConnectionManagerCounters #
Show ConnectionManagerCounters Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> ConnectionManagerCounters -> ShowS # show :: ConnectionManagerCounters -> String # showList :: [ConnectionManagerCounters] -> ShowS #
Eq ConnectionManagerCounters Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) :: ConnectionManagerCounters -> ConnectionManagerCounters -> Bool # (/=) :: ConnectionManagerCounters -> ConnectionManagerCounters -> Bool #
Ord ConnectionManagerCounters Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare :: ConnectionManagerCounters -> ConnectionManagerCounters -> Ordering # (<) :: ConnectionManagerCounters -> ConnectionManagerCounters -> Bool # (<=) :: ConnectionManagerCounters -> ConnectionManagerCounters -> Bool # (>) :: ConnectionManagerCounters -> ConnectionManagerCounters -> Bool # (>=) :: ConnectionManagerCounters -> ConnectionManagerCounters -> Bool # max :: ConnectionManagerCounters -> ConnectionManagerCounters -> ConnectionManagerCounters # min :: ConnectionManagerCounters -> ConnectionManagerCounters -> ConnectionManagerCounters #

Mux types

data WithMuxMode (mode :: Mode) a b where Source #

Constructors

WithInitiatorMode :: forall a b. a -> WithMuxMode 'InitiatorMode a b
WithResponderMode :: forall b a. b -> WithMuxMode 'ResponderMode a b
WithInitiatorResponderMode :: forall a b. a -> b -> WithMuxMode 'InitiatorResponderMode a b

withInitiatorMode :: forall (mode :: Mode) a b. HasInitiator mode ~ 'True => WithMuxMode mode a b -> a Source #

withResponderMode :: forall (mode :: Mode) a b. HasResponder mode ~ 'True => WithMuxMode mode a b -> b Source #

Promise

Promise interface, backed by a StrictTMVar.

Making two separate interfaces: PromiseWriter and PromiseReader allows us to make a clear distinction between consumer and producers threads.

newEmptyPromiseIO :: (MonadSTM m, MonadThrow (STM m)) => m (PromiseReader m a, PromiseWriter m a) Source #

newtype PromiseReader (m :: Type -> Type) a Source #

Constructors

PromiseReader
Fields readPromise :: STM m a A blocking read operation.

readPromiseIO :: MonadSTM m => PromiseReader m a -> m a Source #

data PromiseWriter (m :: Type -> Type) a Source #

Constructors

PromiseWriter
Fields writePromise :: a -> STM m () `putPromise`, is a non-blocking operation, it throws `PromiseWriterException` if it would block. forcePromise :: a -> STM m () If the promise is empty it fills it, if it is non-empty it replaces the current value.

data PromiseWriterException Source #

Constructors

PromiseWriterBlocked

Instances

Instances details

Exception PromiseWriterException Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods toException :: PromiseWriterException -> SomeException # fromException :: SomeException -> Maybe PromiseWriterException # displayException :: PromiseWriterException -> String # backtraceDesired :: PromiseWriterException -> Bool #
Show PromiseWriterException Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> PromiseWriterException -> ShowS # show :: PromiseWriterException -> String # showList :: [PromiseWriterException] -> ShowS #

Tracing

data AssertionLocation peerAddr Source #

AssertionLocation contains constructors that situate the location of the tracing so one can be sure where the assertion came from as well as the all relevant information.

Constructors

ReleaseInboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
AcquireOutboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
ReleaseOutboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
PromotedToWarmRemote !(Maybe (ConnectionId peerAddr)) !AbstractState
DemotedToColdRemote !(Maybe (ConnectionId peerAddr)) !AbstractState

Instances

Instances details

Show peerAddr => Show (AssertionLocation peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> AssertionLocation peerAddr -> ShowS # show :: AssertionLocation peerAddr -> String # showList :: [AssertionLocation peerAddr] -> ShowS #

data MaybeUnknown state Source #

A custom version of Maybe type, which allows to explicitly represent connections which are not registered by the connection manager.

Constructors

Known !state	Known connection in `state`
Race !state	There is a possible race condition between connection finalizer and either inbound or outbound connection registration. If that happens we use `Race` constructor.
Unknown	Connection is is not known to the connection manager.

Instances

Instances details

Functor MaybeUnknown Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods fmap :: (a -> b) -> MaybeUnknown a -> MaybeUnknown b # (<$) :: a -> MaybeUnknown b -> MaybeUnknown a #
Show state => Show (MaybeUnknown state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> MaybeUnknown state -> ShowS # show :: MaybeUnknown state -> String # showList :: [MaybeUnknown state] -> ShowS #

data Transition' state Source #

Constructors

Transition
Fields fromState :: !state toState :: !state

Instances

Instances details

Functor Transition' Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods fmap :: (a -> b) -> Transition' a -> Transition' b # (<$) :: a -> Transition' b -> Transition' a #
Show state => Show (Transition' state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> Transition' state -> ShowS # show :: Transition' state -> String # showList :: [Transition' state] -> ShowS #
Eq state => Eq (Transition' state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) :: Transition' state -> Transition' state -> Bool # (/=) :: Transition' state -> Transition' state -> Bool #

type Transition state = Transition' (MaybeUnknown state) Source #

type AbstractTransition = Transition' AbstractState Source #

mkTransition :: state -> state -> Transition state Source #

mkAbsTransition :: AbstractState -> AbstractState -> AbstractTransition Source #

type TransitionTrace peerAddr state = TransitionTrace' peerAddr (MaybeUnknown state) Source #

data TransitionTrace' peerAddr state Source #

Constructors

TransitionTrace
Fields ttPeerAddr :: peerAddr ttTransition :: Transition' state

Instances

Instances details

Functor (TransitionTrace' peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods fmap :: (a -> b) -> TransitionTrace' peerAddr a -> TransitionTrace' peerAddr b # (<$) :: a -> TransitionTrace' peerAddr b -> TransitionTrace' peerAddr a #
(Show peerAddr, Show state) => Show (TransitionTrace' peerAddr state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> TransitionTrace' peerAddr state -> ShowS # show :: TransitionTrace' peerAddr state -> String # showList :: [TransitionTrace' peerAddr state] -> ShowS #

type AbstractTransitionTrace peerAddr = TransitionTrace' peerAddr AbstractState Source #