futhark-server-1.2.3.0: Client implementation of the Futhark server protocol.

Safe Haskell | None
Language | Haskell2010

Futhark.Server

Contents

- Server creation
- Commands
  - Main commands
  - Interrogation
  - Records
  - Auxiliary
- 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 Source # show :: CmdFailure -> String Source # showList :: [CmdFailure] -> ShowS Source #
Eq CmdFailure Source # |
Instance details Defined in Futhark.Server Methods (==) :: CmdFailure -> CmdFailure -> Bool Source # (/=) :: CmdFailure -> CmdFailure -> Bool Source #
Ord CmdFailure Source # |

Instance details

Defined in Futhark.Server

Methods

compare :: CmdFailure -> CmdFailure -> Ordering Source #

(<) :: CmdFailure -> CmdFailure -> Bool Source #

(<=) :: CmdFailure -> CmdFailure -> Bool Source #

(>) :: CmdFailure -> CmdFailure -> Bool Source #

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

max :: CmdFailure -> CmdFailure -> CmdFailure Source #

min :: CmdFailure -> CmdFailure -> CmdFailure Source #

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.