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


-- | Client implementation of the Futhark server protocol.
--   
--   Provides an easy way to interact with a running Futhark server-mode
--   program from a Haskell program. Provides both direct support of the
--   protocol, as well as convenience functions for loading and extracting
--   data.
@package futhark-server
@version 1.2.2.0


-- | Haskell code for interacting with a Futhark server program. This
--   module presents a low-level interface. See
--   &lt;<a>https://futhark.readthedocs.io/en/latest/server-protocol.html</a>
--   the documentation of the server protocol&gt; for the meaning of the
--   commands. See also <a>Futhark.Server.Values</a> for higher-level
--   functions for loading data into a server.
--   
--   Error messages produced by the server will be returned as a
--   <a>CmdFailure</a>. However, certain errors (such as if the server
--   process terminates unexpectedly, or temporary files cannot be created)
--   will result in an IO exception.
--   
--   Many of the functions here are documented only as the server protocol
--   command they correspond to. See the protocol documentation for
--   details.
module Futhark.Server

-- | A handle to a running server.
data Server

-- | Configuration of the server. Use <a>newServerCfg</a> to conveniently
--   create a sensible default configuration.
data ServerCfg
ServerCfg :: FilePath -> [String] -> Bool -> (Cmd -> Text -> IO ()) -> ServerCfg

-- | Path to the server executable.
[cfgProg] :: ServerCfg -> FilePath

-- | Command line options to pass to the server executable.
[cfgProgOpts] :: ServerCfg -> [String]

-- | If true, print a running log of server communication to stderr.
[cfgDebug] :: ServerCfg -> Bool

-- | A function that is invoked on every line of input sent by the server,
--   except the <tt>%%% OK</tt> and <tt>%%% FAILURE</tt> prompts. This can
--   be used to e.g. print or gather logging messages as they arrive,
--   instead of waiting for the command to finish. The name of the command
--   leading to the message is also provided. The default function does
--   nothing.
[cfgOnLine] :: ServerCfg -> Cmd -> Text -> IO ()

-- | Create a server config with the given <a>cfgProg</a> and
--   <a>cfgProgOpts</a>.
newServerCfg :: FilePath -> [String] -> ServerCfg

-- | Start a server, execute an action, then shut down the server. The
--   <a>Server</a> may not be returned from the action.
withServer :: ServerCfg -> (Server -> IO a) -> IO a

-- | The name of a command.
type Cmd = Text

-- | The command failed, and this is why. The first <a>Text</a> is any
--   output before the failure indicator, and the second Text is the output
--   after the indicator.
data CmdFailure
CmdFailure :: [Text] -> [Text] -> CmdFailure
[failureLog] :: CmdFailure -> [Text]
[failureMsg] :: CmdFailure -> [Text]

-- | The name of a server-side variable.
type VarName = Text

-- | The name of a server-side type.
type TypeName = Text

-- | The name of an entry point.
type EntryName = Text

-- | The type of an input of an entry point. If <a>inputConsumed</a>, then
--   the value passed in a <a>cmdCall</a> must not be used again (nor any
--   of its aliases).
data InputType
InputType :: Bool -> TypeName -> InputType
[inputConsumed] :: InputType -> Bool
[inputType] :: InputType -> TypeName

-- | The type of an output of an entry point. If <a>outputUnique</a>, then
--   the value returned does not alias any of the inputs. See the Futhark
--   language manual itself for more details - the implications are quite
--   subtle (but you can ignore them unless you manually use type
--   annotations to make some entry point parameters unique).
data OutputType
OutputType :: Bool -> TypeName -> OutputType
[outputUnique] :: OutputType -> Bool
[outputType] :: OutputType -> TypeName

-- | <tt>restore filename var0 type0 var1 type1...</tt>.
cmdRestore :: Server -> FilePath -> [(VarName, TypeName)] -> IO (Maybe CmdFailure)

-- | <tt>store filename vars...</tt>.
cmdStore :: Server -> FilePath -> [VarName] -> IO (Maybe CmdFailure)

-- | <tt>call entrypoint outs... ins...</tt>.
cmdCall :: Server -> EntryName -> [VarName] -> [VarName] -> IO (Either CmdFailure [Text])

-- | <tt>free vars...</tt>.
cmdFree :: Server -> [VarName] -> IO (Maybe CmdFailure)

-- | <tt>rename oldname newname</tt>.
cmdRename :: Server -> VarName -> VarName -> IO (Maybe CmdFailure)

-- | <tt>inputs entryname</tt>, with uniqueness represented as True.
cmdInputs :: Server -> EntryName -> IO (Either CmdFailure [InputType])

-- | <tt>outputs entryname</tt>, with uniqueness represented as True.
cmdOutputs :: Server -> EntryName -> IO (Either CmdFailure [OutputType])

-- | <pre>
--   clear
--   </pre>
cmdClear :: Server -> IO (Maybe CmdFailure)

-- | <pre>
--   types
--   </pre>
cmdTypes :: Server -> IO (Either CmdFailure [Text])

-- | <pre>
--   entry_points
--   </pre>
cmdEntryPoints :: Server -> IO (Either CmdFailure [Text])

-- | <pre>
--   new var0 type var1...
--   </pre>
cmdNew :: Server -> Text -> Text -> [Text] -> IO (Maybe CmdFailure)

-- | <pre>
--   project to from field
--   </pre>
cmdProject :: Server -> Text -> Text -> Text -> IO (Maybe CmdFailure)

-- | <pre>
--   fields type
--   </pre>
cmdFields :: Server -> Text -> IO (Either CmdFailure [Text])

-- | <pre>
--   report
--   </pre>
cmdReport :: Server -> IO (Either CmdFailure [Text])

-- | <pre>
--   pause_profiling
--   </pre>
cmdPauseProfiling :: Server -> IO (Maybe CmdFailure)

-- | <pre>
--   unpause_profiling
--   </pre>
cmdUnpauseProfiling :: Server -> IO (Maybe CmdFailure)

-- | <pre>
--   set_tuning_param param value
--   </pre>
cmdSetTuningParam :: Server -> Text -> Text -> IO (Either CmdFailure [Text])

-- | <pre>
--   tuning_params
--   </pre>
cmdTuningParams :: Server -> Text -> IO (Either CmdFailure [Text])

-- | <pre>
--   tuning_param_class param
--   </pre>
cmdTuningParamClass :: Server -> Text -> IO (Either CmdFailure Text)

-- | Turn a <a>Maybe</a>-producing command into a monadic action.
cmdMaybe :: (MonadError Text m, MonadIO m) => IO (Maybe CmdFailure) -> m ()

-- | Turn an <a>Either</a>-producing command into a monadic action.
cmdEither :: (MonadError Text m, MonadIO m) => IO (Either CmdFailure a) -> m a

-- | Start up a server. Make sure that <a>stopServer</a> is eventually
--   called on the server. If this does not happen, then temporary files
--   may be left on the file system. You almost certainly wish to use
--   <a>bracket</a> or similar to avoid this. Calls <a>error</a> if startup
--   fails.
startServer :: ServerCfg -> IO Server

-- | Shut down a server. It may not be used again. Calls <a>error</a> if
--   the server process terminates with a failing exit code (i.e. anything
--   but <a>ExitSuccess</a>).
stopServer :: Server -> IO ()

-- | Send an arbitrary command to the server. This is only useful when the
--   server protocol has been extended without this module having been
--   similarly extended. Be careful not to send invalid commands.
sendCommand :: Server -> Cmd -> [Text] -> IO (Either CmdFailure [Text])
instance GHC.Show.Show Futhark.Server.CmdFailure
instance GHC.Classes.Ord Futhark.Server.CmdFailure
instance GHC.Classes.Eq Futhark.Server.CmdFailure


-- | Convenience functions builds on top of <a>Futhark.Data</a> and
--   <a>Futhark.Server</a> for passing non-opaque values in and out of a
--   server instance.
module Futhark.Server.Values

-- | Retrieve a non-opaque value from the server.
getValue :: Server -> VarName -> IO (Either Text Value)

-- | Store a non-opaque value in the server. A variable with the given name
--   must not already exist (use <a>cmdFree</a> to free it first if
--   necessary).
putValue :: Server -> VarName -> Value -> IO (Maybe CmdFailure)