Futhark.Server

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.

Server creation

data Server

A handle to a running server.

data ServerCfg

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

Create a server config with the given cfgProg and cfgProgOpts.

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

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

Commands

type Cmd = Text

The name of a command.

data CmdFailure

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

Eq CmdFailure

Defined in Futhark.Server

Methods

(==) :: CmdFailure -> CmdFailure -> Bool

(/=) :: CmdFailure -> CmdFailure -> Bool

Ord CmdFailure

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

Show CmdFailure

Defined in Futhark.Server

Methods

showsPrec :: Int -> CmdFailure -> ShowS

show :: CmdFailure -> String

showList :: [CmdFailure] -> ShowS

type VarName = Text

The name of a server-side variable.

type TypeName = Text

The name of a server-side type.

type EntryName = Text

The name of an entry point.

data InputType

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

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)

restore filename var0 type0 var1 type1....

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

store filename vars....

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

call entrypoint outs... ins....

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

free vars....

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

rename oldname newname.

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

inputs entryname, with uniqueness represented as True.

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

outputs entryname, with uniqueness represented as True.

cmdClear :: Server -> IO (Maybe CmdFailure)

clear

Interrogation

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

types

cmdEntryPoints :: Server -> IO (Maybe CmdFailure)

entry_points

Records

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

new var0 type var1...

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

project to from field

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

fields type

Auxiliary

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

report

cmdPauseProfiling :: Server -> IO (Maybe CmdFailure)

pause_profiling

cmdUnpauseProfiling :: Server -> IO (Maybe CmdFailure)

unpause_profiling

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

set_tuning_param param value

Utility

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

Turn a Maybe-producing command into a monadic action.

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

Turn an Either-producing command into a monadic action.

Raw

startServer :: ServerCfg -> IO Server

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

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

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

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.