Thread Class

A thread is like a process within a process -- a single process can have multiple threads. Each thread effectively runs independently of any other thread.

Carapace supports multi-threading, where each thread executes its own script command.

Thread Creation

The create function can be used to create a thread:

    (create Thread "example" (list (quote worker) 100) )

creates a thread called example which executes the script function worker. A suitable candidate for this worker function is as follows:

    (defun String worker ( (n Integer) )

        (while (> n 0)

            (sleep 1000)

            (print n)

            (set n (- n 1))
        )
    
        (return "finished")
    )

which simply counts down by one every second until zero is reached.

Note that a thread starts to run as soon as it is created.

Thread Properties

property name	property type	description
`name`	String	the name of the thread
`expression`	List	the expression to be evaluated by the thread
`result`	Object	the result of the evaluation -- before the thread has finished, this property has a value of the empty List `()`
`error`	Object	if the evaluation raises an error, the error is stored here -- this property has value of an Error or is the empty List `()`
`final`	Object	expression to evaluate when this thread is destroyed -- this can be used to notify the thread that termination is happening
`event`	Event	the event which wraps up the the thread handle -- waiting on this event is equivalent to waiting for this thread to finish

Thread Methods

method name	description
`start`	start evaluating the expression
`stop`	stop evaluating the expression
`suspend`	suspend evaluation of the expression
`resume`	resume evaluation of the expression
`finished`	determine if the thread has finished

`start`

Start evaluating the expression. Since a thread starts to run as soon as it is created, the only time that start is needed is to re-start a stopped thread.

Arguments: none

Return type: if successfully started, the Symbol ok is returned, otherwise the empty List ()

`stop`

Stop evaluating the expression. This attempts to stop the thread gracefully, by requesting a stop and waiting within a time period for evaluation to stop.

Arguments:

gracePeriod Integer

Return type: if successfully stopped, the Symbol ok is returned, otherwise the empty List ()

`suspend`

Suspend evaluation of the expression.

Arguments: none

Return type: if successfully suspended, the Symbol ok is returned, otherwise the empty List ()

`resume`

Resume evaluation of the expression.

Arguments: none

Return type: if successfully suspended, the Symbol ok is returned, otherwise the empty List ()

`finished`

Determine if the thread has finished -- returns true if the thread has finished, () otherwise

Arguments: none

Return type: if the thread has finished, the Symbol true is returned, otherwise the empty List ()

Contents

Index

Current topic: objects