Safe Haskell	Safe-Inferred
Language	Haskell2010

Futhark.Server

Contents

Server creation
Commands
Utility
Raw

Description

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.

Synopsis

data Server
data ServerCfg = ServerCfg {
- cfgProg :: FilePath
- cfgProgOpts :: [String]
- cfgDebug :: Bool
- cfgOnLine :: Cmd -> Text -> IO ()
}
newServerCfg :: FilePath -> [String] -> ServerCfg
withServer :: ServerCfg -> (Server -> IO a) -> IO a
type Cmd = Text
data CmdFailure = CmdFailure {
- failureLog :: [Text]
- failureMsg :: [Text]
}
type VarName = Text
type TypeName = Text
type EntryName = Text
data InputType = InputType {
- inputConsumed :: Bool
- inputType :: TypeName
}
data OutputType = OutputType {
- outputUnique :: Bool
- outputType :: TypeName
}
cmdRestore :: Server -> FilePath -> [(VarName, TypeName)] -> IO (Maybe CmdFailure)
cmdStore :: Server -> FilePath -> [VarName] -> IO (Maybe CmdFailure)
cmdCall :: Server -> EntryName -> [VarName] -> [VarName] -> IO (Either CmdFailure [Text])
cmdFree :: Server -> [VarName] -> IO (Maybe CmdFailure)
cmdRename :: Server -> VarName -> VarName -> IO (Maybe CmdFailure)
cmdInputs :: Server -> EntryName -> IO (Either CmdFailure [InputType])
cmdOutputs :: Server -> EntryName -> IO (Either CmdFailure [OutputType])
cmdClear :: Server -> IO (Maybe CmdFailure)
cmdTypes :: Server -> IO (Either CmdFailure [Text])
cmdEntryPoints :: Server -> IO (Either CmdFailure [Text])
cmdNew :: Server -> Text -> Text -> [Text] -> IO (Maybe CmdFailure)
cmdProject :: Server -> Text -> Text -> Text -> IO (Maybe CmdFailure)
cmdFields :: Server -> Text -> IO (Either CmdFailure [Text])
cmdReport :: Server -> IO (Either CmdFailure [Text])
cmdPauseProfiling :: Server -> IO (Maybe CmdFailure)
cmdUnpauseProfiling :: Server -> IO (Maybe CmdFailure)
cmdSetTuningParam :: Server -> Text -> Text -> IO (Either CmdFailure [Text])
cmdTuningParams :: Server -> Text -> IO (Either CmdFailure [Text])
cmdTuningParamClass :: Server -> Text -> IO (Either CmdFailure Text)
cmdMaybe :: (MonadError Text m, MonadIO m) => IO (Maybe CmdFailure) -> m ()
cmdEither :: (MonadError Text m, MonadIO m) => IO (Either CmdFailure a) -> m a
startServer :: ServerCfg -> IO Server
stopServer :: Server -> IO ()
abortServer :: Server -> IO ()
sendCommand :: Server -> Cmd -> [Text] -> IO (Either CmdFailure [Text])

Server creation

data Server Source #

A handle to a running server.

data ServerCfg Source #

Configuration of the server. Use newServerCfg to conveniently create a sensible default configuration.

Constructors

ServerCfg

Fields

cfgProg :: FilePath
Path to the server executable.
cfgProgOpts :: [String]
Command line options to pass to the server executable.
cfgDebug :: Bool
If true, print a running log of server communication to stderr.
cfgOnLine :: Cmd -> Text -> IO ()
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.

newServerCfg :: FilePath -> [String] -> ServerCfg Source #

Create a server config with the given cfgProg and cfgProgOpts.

withServer :: ServerCfg -> (Server -> IO a) -> IO a Source #

Start a server, execute an action, then shut down the server. The Server may not be returned from the action.

Commands

type Cmd = Text Source #

The name of a command.

data CmdFailure Source #

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.

Constructors

CmdFailure
Fields failureLog :: [Text] failureMsg :: [Text]

Instances

Instances details

Show CmdFailure Source #
Instance details Defined in Futhark.Server Methods showsPrec :: Int -> CmdFailure -> ShowS # show :: CmdFailure -> String # showList :: [CmdFailure] -> ShowS #
Eq CmdFailure Source #
Instance details Defined in Futhark.Server Methods (==) :: CmdFailure -> CmdFailure -> Bool # (/=) :: CmdFailure -> CmdFailure -> Bool #
Ord CmdFailure Source #
Instance details Defined in Futhark.Server Methods compare :: CmdFailure -> CmdFailure -> Ordering # (<) :: CmdFailure -> CmdFailure -> Bool # (<=) :: CmdFailure -> CmdFailure -> Bool # (>) :: CmdFailure -> CmdFailure -> Bool # (>=) :: CmdFailure -> CmdFailure -> Bool # max :: CmdFailure -> CmdFailure -> CmdFailure # min :: CmdFailure -> CmdFailure -> CmdFailure #

type VarName = Text Source #

The name of a server-side variable.

type TypeName = Text Source #

The name of a server-side type.

type EntryName = Text Source #

The name of an entry point.

data InputType Source #

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

Constructors

InputType
Fields inputConsumed :: Bool inputType :: TypeName

data OutputType Source #

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

Constructors

OutputType
Fields outputUnique :: Bool outputType :: TypeName

Main commands

cmdRestore :: Server -> FilePath -> [(VarName, TypeName)] -> IO (Maybe CmdFailure) Source #

restore filename var0 type0 var1 type1....

cmdStore :: Server -> FilePath -> [VarName] -> IO (Maybe CmdFailure) Source #

store filename vars....

cmdCall :: Server -> EntryName -> [VarName] -> [VarName] -> IO (Either CmdFailure [Text]) Source #

call entrypoint outs... ins....

cmdFree :: Server -> [VarName] -> IO (Maybe CmdFailure) Source #

free vars....

cmdRename :: Server -> VarName -> VarName -> IO (Maybe CmdFailure) Source #

rename oldname newname.

cmdInputs :: Server -> EntryName -> IO (Either CmdFailure [InputType]) Source #

inputs entryname, with uniqueness represented as True.

cmdOutputs :: Server -> EntryName -> IO (Either CmdFailure [OutputType]) Source #

outputs entryname, with uniqueness represented as True.

cmdClear :: Server -> IO (Maybe CmdFailure) Source #

clear

Interrogation

cmdTypes :: Server -> IO (Either CmdFailure [Text]) Source #

types

cmdEntryPoints :: Server -> IO (Either CmdFailure [Text]) Source #

entry_points

Records

cmdNew :: Server -> Text -> Text -> [Text] -> IO (Maybe CmdFailure) Source #

new var0 type var1...

cmdProject :: Server -> Text -> Text -> Text -> IO (Maybe CmdFailure) Source #

project to from field

cmdFields :: Server -> Text -> IO (Either CmdFailure [Text]) Source #

fields type

Auxiliary

cmdReport :: Server -> IO (Either CmdFailure [Text]) Source #

report

cmdPauseProfiling :: Server -> IO (Maybe CmdFailure) Source #

pause_profiling

cmdUnpauseProfiling :: Server -> IO (Maybe CmdFailure) Source #

unpause_profiling

cmdSetTuningParam :: Server -> Text -> Text -> IO (Either CmdFailure [Text]) Source #

set_tuning_param param value

cmdTuningParams :: Server -> Text -> IO (Either CmdFailure [Text]) Source #

tuning_params

cmdTuningParamClass :: Server -> Text -> IO (Either CmdFailure Text) Source #

tuning_param_class param

Utility

cmdMaybe :: (MonadError Text m, MonadIO m) => IO (Maybe CmdFailure) -> m () Source #

Turn a Maybe-producing command into a monadic action.

cmdEither :: (MonadError Text m, MonadIO m) => IO (Either CmdFailure a) -> m a Source #

Turn an Either-producing command into a monadic action.

Raw

startServer :: ServerCfg -> IO Server Source #

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.

stopServer :: Server -> IO () Source #

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

abortServer :: Server -> IO () Source #

Terminate the server process. You'll still need to call stopServer unless used inside withServer, which does it for you.

sendCommand :: Server -> Cmd -> [Text] -> IO (Either CmdFailure [Text]) Source #

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.