-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Library to control network protocols
--   
--   Common parts to control network protocols
@package network-control
@version 0.1.3


-- | Common parts to control network protocols. This library assumes that
--   <a>Int</a> is 64bit.
module Network.Control

-- | Default max streams. (64)
defaultMaxStreams :: Int

-- | Default max data of a stream. (256K bytes)
defaultMaxStreamData :: Int

-- | Default max data of a connection.
--   
--   By default, this is set to <tt>defaultMaxStreams *
--   defaultMaxStreamData</tt>. This ensures that streams that are not
--   currently handled cannot exhaust the connection window.
--   
--   If you use a smaller connection window size, you <b>must</b> ensure
--   that if you are handling fewer concurrent streams than allowed by
--   <a>defaultMaxStreams</a>, that the unhandled streams cannot exhaust
--   the connection window, or risk the entire system deadlocking.
defaultMaxData :: Int

-- | Flow for sending
--   
--   <pre>
--   --------------------------------------&gt;
--          ^           ^
--       txfSent    txfLimit
--   
--          |-----------| The size which this node can send
--          txWindowSize
--   </pre>
data TxFlow
TxFlow :: Int -> Int -> TxFlow

-- | The total size of sent data.
[txfSent] :: TxFlow -> Int

-- | The total size of data which can be sent.
[txfLimit] :: TxFlow -> Int

-- | Creating TX flow with a receive buffer size.
newTxFlow :: WindowSize -> TxFlow

-- | <a>txfLimit</a> - <a>txfSent</a>.
txWindowSize :: TxFlow -> WindowSize

-- | Window size.
type WindowSize = Int

-- | Flow for receiving.
--   
--   The goal of <a>RxFlow</a> is to ensure that our network peer does not
--   send us data faster than we can consume it. We therefore impose a
--   maximum number of unconsumed bytes that we are willing to receive from
--   the peer, which we refer to as the buffer size:
--   
--   <pre>
--                      rxfBufSize
--             |---------------------------|
--   --------------------------------------------&gt;
--             ^              ^
--        rxfConsumed    rxvReceived
--   </pre>
--   
--   The peer does not know of course how many bytes we have consumed of
--   the data that they sent us, so they keep track of their own limit of
--   how much data they are allowed to send. We keep track of this limit
--   also:
--   
--   <pre>
--                      rxfBufSize
--             |---------------------------|
--   --------------------------------------------&gt;
--             ^              ^       ^
--        rxfConsumed    rxvReceived  |
--                                 rxfLimit
--   </pre>
--   
--   Each time we receive data from the peer, we check that they do not
--   exceed the limit (<a>checkRxLimit</a>). When we consume data, we
--   periodically send the peer an update (known as a _window update_) of
--   what their new limit is (<a>maybeOpenRxWindow</a>). To decrease
--   overhead, we only this if the window update is at least half the
--   window size.
data RxFlow
RxFlow :: Int -> Int -> Int -> Int -> RxFlow

-- | Maxinum number of unconsumed bytes the peer can send us
--   
--   See discussion above for details.
[rxfBufSize] :: RxFlow -> Int

-- | How much of the data that the peer has sent us have we consumed?
--   
--   This is an absolute number: the total about of bytes consumed over the
--   lifetime of the connection or stream (i.e., not relative to the
--   window).
[rxfConsumed] :: RxFlow -> Int

-- | How much data have we received from the peer?
--   
--   Like <a>rxfConsumed</a>, this is an absolute number.
[rxfReceived] :: RxFlow -> Int

-- | Current limit on how many bytes the peer is allowed to send us.
--   
--   Like 'rxfConsumed, this is an absolute number.
[rxfLimit] :: RxFlow -> Int

-- | Creating RX flow with an initial window size.
newRxFlow :: WindowSize -> RxFlow

-- | <a>rxfLimit</a> - <a>rxfReceived</a>.
--   
--   This is the number of bytes the peer is still allowed to send before
--   they must wait for a window update; see <a>RxFlow</a> for details.
rxWindowSize :: RxFlow -> WindowSize

-- | The representation of window size update.
data FlowControlType

-- | HTTP/2 style
FCTWindowUpdate :: FlowControlType

-- | QUIC style
FCTMaxData :: FlowControlType

-- | Record that we have consumed some received data
--   
--   May return a window update; see <a>RxFlow</a> for details.
maybeOpenRxWindow :: Int -> FlowControlType -> RxFlow -> (RxFlow, Maybe Int)

-- | Checking if received data is acceptable against the current window.
checkRxLimit :: Int -> RxFlow -> (RxFlow, Bool)

-- | Sized cache based on least recently used.
data LRUCache k v

-- | Empty <a>LRUCache</a>.
empty :: Int -> LRUCache k v

-- | Inserting.
insert :: Ord k => k -> v -> LRUCache k v -> LRUCache k v

-- | Deleting.
delete :: Ord k => k -> LRUCache k v -> LRUCache k v

-- | Looking up.
lookup :: Ord k => k -> LRUCache k v -> Maybe v

-- | Type for rating.
data Rate

-- | Creating a new <a>Rate</a>.
newRate :: IO Rate

-- | Getting the current rate. If one or more seconds have passed since the
--   previous call, the counter is re-initialized with 1 and it is
--   returned. Otherwise, incremented counter number is returned.
getRate :: Rate -> IO Int

-- | Getting the current rate. If one or more seconds have passed since the
--   previous call, the counter is re-initialized with the second argument
--   and it is returned. Otherwise, increased counter number is returned.
addRate :: Rate -> Int -> IO Int