Module "Ports.curry"

Library for distributed programming with ports. This paper contains a description of the basic ideas behind this library.

Author: Michael Hanus

Version: April 2007

Exported names:

Datatypes:
Port | SP_Msg

Constructors:
SP_Close | SP_EOF | SP_GetChar | SP_GetLine | SP_Put

Summary of exported functions:

openPort :: Port a -> [a] -> Success

Opens an internal port for communication.

send :: a -> Port a -> Success

Sends a message to a port.

doSend :: a -> Port a -> IO ()

I/O action that sends a message to a port.

ping :: Int -> Port a -> IO (Maybe Int)

Checks whether port p is still reachable.

timeoutOnStream :: Int -> [a] -> Maybe [a]

Checks for instantiation of a stream within some amount of time.

openProcessPort :: String -> IO (Port SP_Msg)

Opens a new connection to a process that executes a shell command.

openNamedPort :: String -> IO [a]

Opens an external port with a symbolic name.

connectPortRepeat :: Int -> IO a -> Int -> String -> IO (Maybe (Port b))

Waits for connection to an external port.

connectPortWait :: String -> IO (Port a)

Waits for connection to an external port and return the connected port.

connectPort :: String -> IO (Port a)

Connects to an external port.

choiceSPEP :: Port SP_Msg -> [a] -> Either String [a]

This function implements a committed choice over the receiving of messages via a stream port and an external port.

newObject :: (a -> [b] -> Success) -> a -> Port b -> Success

Creates a new object (of type State -> [msg] -> Success) with an initial state and a port to which messages for this object can be sent.

newNamedObject :: (a -> [b] -> Success) -> a -> String -> IO ()

Creates a new object (of type State -> [msg] -> Success) with a symbolic port name to which messages for this object can be sent.

runNamedServer :: ([a] -> IO b) -> String -> IO b

Runs a new server (of type [msg] -> IO a) on a named port to which messages can be sent.

Imported modules:

CPNS
Prelude
System
Time

Exported datatypes:

Port

The internal constructor for the port datatype is not visible to the user.

Constructors:

A "stream port" is an adaption of the port concept to model the communication with bidirectional streams, i.e., a stream port is a port connection to a bidirectional stream (e.g., opened by openProcessPort) where the communication is performed via the following stream port messages.

Constructors:

SP_Put:: String -> SP_Msg: SP_Put s - write the argument s on the output stream
SP_GetLine:: String -> SP_Msg: SP_GetLine s - unify the argument s with the next text line of the input stream
SP_GetChar:: Char -> SP_Msg: SP_GetChar c - unify the argument c with the next character of the input stream
SP_EOF:: Bool -> SP_Msg: SP_EOF b - unify the argument b with True if we are at the end of the input stream, otherwise with False
SP_Close:: SP_Msg: SP_Close - close the input/output streams

Exported functions:

openPort :: Port a -> [a] -> Success

Opens an internal port for communication.

Example call: (openPort p s)

Parameters:
: p - a free variable which will be constrained with the port messages
: s - a free variable which will be instantiated to the stream of incoming messages

send :: a -> Port a -> Success

Sends a message to a port.

doSend :: a -> Port a -> IO ()

I/O action that sends a message to a port.

Further infos:

might behave indeterministically

ping :: Int -> Port a -> IO (Maybe Int)

Checks whether port p is still reachable.

Example call: (ping n p)

Parameters:
: n - the time to wait for reachability in milliseconds
: p - a port to be checked for reachability

Returns:: Nothing if port p is unreachable within n milliseconds, or (Just m) if port p could be contacted within m milliseconds

timeoutOnStream :: Int -> [a] -> Maybe [a]

Checks for instantiation of a stream within some amount of time.

Example call: (timeoutOnStream n str)

Parameters:
: n - the time to wait for instantiation in milliseconds
: str - the stream to be checked for instantiation (usually the stream of incoming messages at some port)

Returns:: (Just str) if str is instantiated within n milliseconds, or Nothing otherwise

openProcessPort :: String -> IO (Port SP_Msg)

Opens a new connection to a process that executes a shell command.

Example call: (openProcessPort cmd)

Parameters:
: cmd - the shell command to be executed

Returns:: the output/input stream (represented as a stream port) that is connected to the standard input/output of the process performing the execution of cmd.

openNamedPort :: String -> IO [a]

Opens an external port with a symbolic name.

Example call: (openNamedPort portname)

Parameters:
: portname - the symbolic name under which the port is accessible (any string without occurrences of '@')

Returns:: the stream of incoming messages at this port

connectPortRepeat :: Int -> IO a -> Int -> String -> IO (Maybe (Port b))

Waits for connection to an external port. In contrast to connectPort, this action waits until the external port has been registered with its symbolic name.

Example call: (connectPortRepeat waittime action retries portname)

Parameters:
: waittime - the time to wait before retrying (in milliseconds)
: action - I/O action to be executed before each wait cycle
: retries - number of retries before giving up (-1 = retry forever)
: portname - the symbolic name of the external port (must be either of the form "name@machine" or "name" where the latter is a shorthand for "name@localhost")

Returns:: Nothing (if connection is not possible within the given limits) or (Just p) where p is a port with the symbolic name portname

connectPortWait :: String -> IO (Port a)

Waits for connection to an external port and return the connected port. This action waits (possibly forever) until the external port is registered.

Example call: (connectPortWait portname)

Parameters:
: portname - the symbolic name of the external port (must be either of the form "name@host" or "name" where the latter is a shorthand for "name@localhost")

Returns:: a port with the symbolic name portname

connectPort :: String -> IO (Port a)

Connects to an external port. The external port must be already registered, otherwise an error is reported.

Example call: (connectPort portname)

Parameters:
: portname - the symbolic name of the external port (must be either of the form "name@host" or "name" where the latter is a shorthand for "name@localhost")

Returns:: a port with the symbolic name portname

choiceSPEP :: Port SP_Msg -> [a] -> Either String [a]

This function implements a committed choice over the receiving of messages via a stream port and an external port.
Note that the implementation of choiceSPEP works only with Sicstus-Prolog 3.8.5 or higher (due to a bug in previous versions of Sicstus-Prolog).

Example call: (choiceSPEP sp ms)

Parameters:
: sp - a stream port sp
: ms - a stream of messages received via an external port

Returns:: (Left s) if s is an input line received at the stream port (via SP_GetLine) or
(Right ms) if the stream ms is instantiated with at least one new message at the head

newObject :: (a -> [b] -> Success) -> a -> Port b -> Success

Creates a new object (of type State -> [msg] -> Success) with an initial state and a port to which messages for this object can be sent.

Example call: (newObject object state port)

Parameters:
: object - an object template
: state - the initial state of the object
: port - a free variable which will be constrained to the port for sending messages to the object

newNamedObject :: (a -> [b] -> Success) -> a -> String -> IO ()

Creates a new object (of type State -> [msg] -> Success) with a symbolic port name to which messages for this object can be sent.

Example call: (newNamedObject object state portname)

Parameters:
: object - an object template
: state - the initial state of the object
: portname - the symbolic name under which the object's port is accessible (any string without occurrences of '@')

runNamedServer :: ([a] -> IO b) -> String -> IO b

Runs a new server (of type [msg] -> IO a) on a named port to which messages can be sent.

Example call: (runNamedServer server portname)

Parameters:
: server - a server function that processes incoming messages
: portname - the symbolic name under which the server's port is accessible (any string without occurrences of '@')

Generated by CurryDoc (Version 0.4.1 of June 7, 2007) at Aug 28 15:25:37 2008