-- 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.7

-- | Common parts to control network protocols. This library assumes that
--   Int 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 defaultMaxStreams *
--   defaultMaxStreamData. This ensures that streams that are not
--   currently handled cannot exhaust the connection window.
--   
--   If you use a smaller connection window size, you must ensure
--   that if you are handling fewer concurrent streams than allowed by
--   defaultMaxStreams, that the unhandled streams cannot exhaust
--   the connection window, or risk the entire system deadlocking.
defaultMaxData :: Int

-- | Flow for sending
--   
--   
--   -------------------------------------->
--          ^           ^
--       txfSent    txfLimit
--   
--          |-----------| The size which this node can send
--          txWindowSize
--   
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

-- | txfLimit - txfSent.
txWindowSize :: TxFlow -> WindowSize

-- | Window size.
type WindowSize = Int

-- | Flow for receiving.
--   
--   The goal of RxFlow 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:
--   
--   
--                      rxfBufSize
--             |---------------------------|
--   -------------------------------------------->
--             ^              ^
--        rxfConsumed    rxvReceived
--   
--   
--   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:
--   
--   
--                      rxfBufSize
--             |---------------------------|
--   -------------------------------------------->
--             ^              ^       ^
--        rxfConsumed    rxvReceived  |
--                                 rxfLimit
--   
--   
--   Each time we receive data from the peer, we check that they do not
--   exceed the limit (checkRxLimit). When we consume data, we
--   periodically send the peer an update (known as a _window update_) of
--   what their new limit is (maybeOpenRxWindow). 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 rxfConsumed, 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

-- | rxfLimit - rxfReceived.
--   
--   This is the number of bytes the peer is still allowed to send before
--   they must wait for a window update; see RxFlow 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 RxFlow for details.
maybeOpenRxWindow :: Int -> FlowControlType -> RxFlow -> (RxFlow, Maybe Int)

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

-- | Empty LRUCache. O(1)
empty :: Int -> LRUCache k v

-- | Looking up. O(log n)
lookup :: Ord k => k -> LRUCache k v -> Maybe v

-- | Deleting. O(log n)
delete :: Ord k => k -> LRUCache k v -> LRUCache k v

-- | Inserting. O(log n)
insert :: Ord k => k -> v -> LRUCache k v -> LRUCache k v

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

-- | Looking up and changing priority. O(log n)
lookup' :: Ord k => k -> LRUCache k v -> Maybe (v, LRUCache k v)

-- | Mutable LRUCache.
data LRUCacheRef k v

-- | Creating LRUCacheRef.
newLRUCacheRef :: Int -> IO (LRUCacheRef k v)

-- | Looking up a target and adjusting the LRU cache. If not found, a new
--   value is inserted. A pair of value and "found" is returned.
cached :: Ord k => LRUCacheRef k v -> k -> IO v -> IO (v, Bool)

-- | Looking up a target and adjusting the LRU cache.
cached' :: Ord k => LRUCacheRef k v -> k -> IO (Maybe v)

-- | Setting capacity of the LRU cache.
setLRUCapacity :: LRUCacheRef k v -> Int -> IO ()

-- | Empty LRUCache. O(1)
empty' :: Int -> Int64 -> LRUCache k v

-- | Type for rating.
data Rate

-- | Creating a new Rate.
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
