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

-- | Haskell code for interacting with a Futhark server program. This
--   module presents a low-level interface. See
--   <https://futhark.readthedocs.io/en/latest/server-protocol.html
--   the documentation of the server protocol> for the meaning of the
--   commands. See also Futhark.Server.Values for higher-level
--   functions for loading data into a server.
--   
--   Error messages produced by the server will be returned as a
--   CmdFailure. 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 newServerCfg 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 output sent by the server,
--   except the %%% OK and %%% FAILURE 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 cfgProg and
--   cfgProgOpts.
newServerCfg :: FilePath -> [String] -> ServerCfg

-- | Start a server, execute an action, then shut down the server. The
--   Server 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 Text 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 inputConsumed, then
--   the value passed in a cmdCall 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 outputUnique, 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

-- | Turn an Either-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 stopServer 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
--   bracket or similar to avoid this. Calls error if startup
--   fails.
startServer :: ServerCfg -> IO Server

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

-- | Terminate the server process. You'll still need to call
--   stopServer unless used inside withServer, which does it
--   for you.
abortServer :: 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.Classes.Eq Futhark.Server.CmdFailure
instance GHC.Classes.Ord Futhark.Server.CmdFailure
instance GHC.Internal.Show.Show Futhark.Server.CmdFailure

-- | Convenience functions built on top of Futhark.Data and
--   Futhark.Server 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 cmdFree to free it first if
--   necessary).
putValue :: Server -> VarName -> Value -> IO (Maybe CmdFailure)
