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


-- | Abstract full system simulator
--   
--   SoOSiM is a simulator developed for the purpose of exploring operating
--   system concepts and operating system modules. The simulator provides a
--   highly abstracted view of a computing system, consisting of computing
--   nodes, and components that are concurrently executed on these nodes.
--   OS modules are subsequently modelled as components that progress as a
--   result of reacting to two types of events: messages from other
--   components, or a system-wide tick event. Using this abstract view, a
--   developer can quickly formalize assertions regarding the interaction
--   between operating system modules and applications.
@package SoOSiM
@version 0.1

module SoOSiM.Types
type ComponentId = Unique
type ComponentName = String

-- | Type class that defines every OS component
class ComponentIface s
initState :: ComponentIface s => s
componentName :: ComponentIface s => s -> ComponentName
componentBehaviour :: ComponentIface s => s -> ComponentInput -> SimM s

-- | Context of a running component in the simulator.
--   
--   We need rank-2 types because we need to make a single collection of
--   several component contexts, each having their own type representing
--   their internal state.
data ComponentContext
CC :: ComponentId -> TVar (ComponentStatus s) -> TVar s -> ComponentId -> TVar [ComponentInput] -> [String] -> TVar SimMetaData -> ComponentContext
componentId :: ComponentContext -> ComponentId

-- | Status of the component
currentStatus :: ComponentContext -> TVar (ComponentStatus s)

-- | State internal to the component
componentState :: ComponentContext -> TVar s

-- | <a>ComponentId</a> of the component that created this component
creator :: ComponentContext -> ComponentId

-- | Message waiting to be processed by the component
msgBuffer :: ComponentContext -> TVar [ComponentInput]

-- | Trace message buffer
traceMsgs :: ComponentContext -> [String]

-- | Statistical information regarding a component
simMetaData :: ComponentContext -> TVar SimMetaData
data SimMetaData
SimMetaData :: Int -> Int -> Int -> Map ComponentId Int -> Map ComponentId Int -> SimMetaData
cyclesRunning :: SimMetaData -> Int
cyclesWaiting :: SimMetaData -> Int
cyclesIdling :: SimMetaData -> Int

-- | Key: senderId; Value: number of messages
msgsReceived :: SimMetaData -> Map ComponentId Int

-- | Key: receiverId: Value: number of messages
msgsSend :: SimMetaData -> Map ComponentId Int

-- | Status of a running component
data ComponentStatus a

-- | Component is doing nothing
Idle :: ComponentStatus a

-- | Component is waiting for a message from <a>ComponentId</a>, will
--   continue with computation (<a>Dynamic</a> -&gt; <a>SimM</a> a) once
--   received
WaitingForMsg :: ComponentId -> (Dynamic -> SimM a) -> ComponentStatus a

-- | Component is busy doing computations
Running :: ComponentStatus a

-- | Events send to components by the simulator
data ComponentInput

-- | A message send another component: the field argument is the
--   <a>ComponentId</a> of the sender, the second field the message content
ComponentMsg :: ComponentId -> Dynamic -> ComponentInput

-- | A message send by a node: the first field is the <a>NodeId</a> of the
--   sending node, the second field the message content
NodeMsg :: NodeId -> Dynamic -> ComponentInput

-- | Event send when a component is first created
Initialize :: ComponentInput

-- | Event send when a component is about to be removed
Deinitialize :: ComponentInput

-- | Event send every simulation round
Tick :: ComponentInput
type NodeId = Unique

-- | Meta-data describing the functionaly of the computing node, currently
--   just a singleton type.
data NodeInfo
NodeInfo :: NodeInfo

-- | Nodes represent computing entities in the simulator, and host the OS
--   components and application threads
data Node
Node :: NodeId -> NodeInfo -> Map ComponentName ComponentId -> IntMap ComponentContext -> IntMap Dynamic -> [ComponentId] -> Node

-- | Globally Unique ID of the node
nodeId :: Node -> NodeId

-- | Meta-data describing the node
nodeInfo :: Node -> NodeInfo

-- | Lookup table of OS components running on the node, key: the
--   <a>ComponentName</a>, value: unique <a>ComponentId</a>
nodeComponentLookup :: Node -> Map ComponentName ComponentId

-- | Map of component contexts, key is the <a>ComponentId</a>
nodeComponents :: Node -> IntMap ComponentContext

-- | Node-local memory
nodeMemory :: Node -> IntMap Dynamic
nodeComponentOrder :: Node -> [ComponentId]
newtype SimM a
SimM :: Coroutine (RequestOrYield Unique Dynamic) SimMonad a -> SimM a
runSimM :: SimM a -> Coroutine (RequestOrYield Unique Dynamic) SimMonad a
data RequestOrYield request response x
Request :: request -> (response -> x) -> RequestOrYield request response x
Yield :: x -> RequestOrYield request response x

-- | The internal monad of the simulator is currently a simple state-monad
--   wrapping IO
type SimMonad = StateT SimState IO

-- | The internal simulator state
data SimState
SimState :: ComponentId -> NodeId -> IntMap Node -> UniqSupply -> Map String StateContainer -> SimState

-- | The <a>ComponentId</a> of the component currently under evaluation
currentComponent :: SimState -> ComponentId

-- | The <a>NodeId</a> of the node containing the component currently under
--   evaluation
currentNode :: SimState -> NodeId

-- | The set of nodes comprising the entire system
nodes :: SimState -> IntMap Node

-- | Unlimited supply of unique values
uniqueSupply :: SimState -> UniqSupply
componentMap :: SimState -> Map String StateContainer
data StateContainer
SC :: s -> StateContainer
instance Typeable Unique
instance Show ComponentInput
instance Functor SimM
instance Monad SimM
instance MonadUnique SimMonad
instance Functor (RequestOrYield x f)

module SoOSiM.Simulator
modifyNode :: NodeId -> (Node -> Node) -> SimMonad ()
modifyNodeM :: NodeId -> (Node -> SimMonad ()) -> SimMonad ()
incrSendCounter :: ComponentId -> ComponentId -> Node -> SimMonad ()
componentNode :: ComponentId -> SimMonad NodeId
updateMsgBuffer :: ComponentId -> ComponentInput -> Node -> SimMonad ()
updateTraceBuffer :: ComponentId -> String -> Node -> Node
execStep :: SimState -> IO SimState
execStepSmall :: SimState -> IO SimState

module SoOSiM
data SimM a
type ComponentId = Unique
type NodeId = Unique

-- | Type class that defines every OS component
class ComponentIface s
initState :: ComponentIface s => s
componentName :: ComponentIface s => s -> ComponentName
componentBehaviour :: ComponentIface s => s -> ComponentInput -> SimM s

-- | Events send to components by the simulator
data ComponentInput

-- | A message send another component: the field argument is the
--   <a>ComponentId</a> of the sender, the second field the message content
ComponentMsg :: ComponentId -> Dynamic -> ComponentInput

-- | A message send by a node: the first field is the <a>NodeId</a> of the
--   sending node, the second field the message content
NodeMsg :: NodeId -> Dynamic -> ComponentInput

-- | Event send when a component is first created
Initialize :: ComponentInput

-- | Event send when a component is about to be removed
Deinitialize :: ComponentInput

-- | Event send every simulation round
Tick :: ComponentInput

-- | Register a component interface with the simulator
registerComponent :: ComponentIface s => s -> SimM ()

-- | Create a new component
createComponent :: Maybe NodeId -> Maybe ComponentId -> String -> SimM ComponentId

-- | Synchronously invoke another component
invoke :: Maybe ComponentId -> ComponentId -> Dynamic -> SimM Dynamic

-- | Invoke another component, don't wait for a response
invokeNoWait :: Maybe ComponentId -> ComponentId -> Dynamic -> SimM ()

-- | Yield to the simulator scheduler
yield :: ComponentIface s => s -> SimM s

-- | Get the component id of your component
getComponentId :: SimM ComponentId

-- | Get the node id of of the node your component is currently running on
getNodeId :: SimM NodeId

-- | Create a new node
createNode :: SimM NodeId

-- | Write memory of local node
writeMemory :: Maybe NodeId -> Int -> Dynamic -> SimM ()

-- | Read memory of local node
readMemory :: Maybe NodeId -> Int -> SimM Dynamic

-- | Return the <a>ComponentId</a> of the component that created the
--   current component
componentCreator :: SimM ComponentId

-- | Get the unique <a>ComponentId</a> of a certain component
componentLookup :: Maybe NodeId -> ComponentName -> SimM (Maybe ComponentId)
runIO :: IO a -> SimM a
traceMsg :: String -> SimM ()