thread Class Reference


The class thread defines the structures and methods needed to create threads and communicate with them. Each new thread inherits a copy of all the data segments of its parent, and thus all the classes, methods and functions defined in the parent at the moment of the creation. The stack of the new thread is a smashed down or compacted version of the stack of the parent, corresponding to the state of the dynamic environment at the moment of the creation. A thread can execute a lot of background things without blocking the console IO for example. Each new thread is automatically provided with a message queue, in which the other thread can put messages, and from which it can read. Message reception can be blocking or non-blocking.

Objects of the class thread are really defined in the thread where they are constructed, so an existing thread has no other way to find which threads are running at a specific instant than calling thread-list-all to obtain a list of the running threads in the process; the objects returned by thread-list-all are valid thread objects useable as thread proxies. To list human readably the existing threads do:

(mapcar 'show (list-all *thisthread*))

which gives the following display for each existing thread:

threadname = "lispmain"
threadid = 1076156384
threadengine = 0x80a3700
baseclasses = (thread class)

The methods thread-check , thread-recv , thread-list-all and thread-time have only a meaning when called on the thread in which they are executing, and thus are always called on *thisthread*.


  • thread-check
  • thread-constructor
  • thread-destructor
  • thread-id
  • thread-list-all
  • thread-name
  • thread-recv
  • thread-send
  • thread-signal
  • thread-time

  • List of all Inherited Classes

  • class

  • thread-check

    (check arg )

    Function Type subr
    Arguments a thread object
    Return Value t or nil
    Description checks if a message in awaiting in the thread message queue without to block if there is none; because there is only one message queue per thread, and thread objects are just thread local proxies to the real threads, check must always be called with *thisthread* as argument
    Example (check *thisthread*)

    thread-constructor

    (make-instance thread arg1 ... argn1 argn2 )

    Function Type subr
    Arguments the symbol thread, a form to evaluate, a series of optional keywords each followed by a value
    Return Value a thread object
    Description never call thread-constructor directly but always through make-instance ; thread-constructor clones completely the running thread; it copies the binary and string segments, copies and relocates the pointer segment and the environment hash table, sets a pointer to the expression to evaluate and launch the thread;

    the form given as first argument to thread-constructor is evaluated by the new thread; when that evaluation is finished, the thread stops and its memory is cleaned-up; the environment of the new thread is a snapshot of the calling environment at the moment of the creation of the thread, thus with the effects of dynamic scoping;

    the new engine parameters values are by default identical to those of the parent thread, but they can be modified via keywords followed by values;

    the keyword 'pointerspace must be followed by an integer which gives in bytes the size of the new pointerspace segment;

    the keyword 'stringspace must be followed by an integer which gives in bytes the size of the new stringspace segment;

    the keyword 'binaryspace must be followed by an integer which gives in bytes the size of the new binaryspace segment;

    the keyword 'maxstring must be followed by an integer which gives in bytes the size of the new maxstring parameter;

    those values must be equal or greater than those of the calling thread, or they are automatically set to those of the calling thread; in other words, as it is not possible to reduce the size of a segment when creating a new thread, if a process must use a lot of threads, the main thread must be small itself;

    the keyword 'stacksize must be followed by an integer which gives in bytes the size of the new stacksize;

    the keyword 'historysize must be followed by an integer which gives in lines the default size of the keyboard history;

    the keyword 'queuesize must be followed by an integer which gives the size of the message queue in 32 or 64 bits words depending on the processor architecture;

    the keywords 'verboseinit , 'signalgarbage , 'donttrapSEGV , 'dontcheckstack , ' consistencycheck , 'jumpwhenabort , 'supergc , 'dumpandabort must be followed by t or nil;

    the symbolicstream stdin , stdout and stderr of the main thread are shared with the secundary threads, the atomicity of the IO being controlled by a mutex specific to each symbolicstream;

    Example (make-instance thread '(loop(sleep 1000)(print 'hello)))

    thread-destructor

    (destroy-instance arg )

    Function Type subr
    Arguments a thread object
    Return Value t
    Description destroys the thread object which establishes a link with a thread, but leaves the thread itself running
    Example (destroy-instance th1)

    thread-id

    (id arg )

    Function Type subr
    Arguments a thread object
    Return Value an integer or nil
    Description checks if the thread is still running, and if true returns an integer which is the thread id
    Example (id *thisthread*) => 1076156384

    thread-list-all

    (list-all arg )

    Function Type subr
    Arguments a thread object
    Return Value a list of thread objects
    Description returns a list containing thread objects useable as proxies to the wwlisp threads running in the process; the argument is always *thisthread*
    Example (list-all *thisthread*)

    thread-name

    (name arg )

    Function Type subr
    Arguments a thread object, an optional string
    Return Value a string
    Description returns the current name of the thread of which the proxy object is given as first argument; if the second argument is given, it is used to set a new name for the thread, which is valid globally in the process; a parent thread can use this feature to name its child thread just after creation; the name returned is the old one, not the new
    Example (name *thisthread* "mythread" ) => "lispmain"
    (name *thisthread*) => "mythread"

    thread-recv

    (recv arg )

    Function Type subr
    Arguments a thread object
    Return Value a list
    Description returns a list containing a message coming from another thread; the first element of the list is the threadid of the sending thread; the following elements constitute the body of the message; a message is made of any number of intermixed items of the types integer, unsigned integer, float, string, atom, t or nil; lists, objects, binary blocks cannot be transmitted directly, except by their address encoded as unsigned integer; the argument is always *thisthread*
    Example (recv *thisthread*)

    thread-send

    (send arg1 arg2 ... argn )

    Function Type subr
    Arguments a thread object, an unlimited number of intermixed integers, unsigned integers, floats, strings, atoms, t or nil
    Return Value t or nil
    Description send a list containing all the arguments from the second on, to the thread identified by the object given as first argument; a thread can also send to itself, but if it tries to receive from itself without having sent something before, it will be blocked forever
    Example (send *thisthread* 'hello) => t

    thread-signal

    (signal arg )

    Function Type subr
    Arguments a thread object
    Return Value nil
    Description sets a flag in the thread given as argument which causes the same effect as if control-c has been hit for that thread
    Example (signal thread1)

    thread-time

    (time arg )

    Function Type subr
    Arguments a thread object
    Return Value a float
    Description returns the elapsed execution time for the calling thread , in milliseconds; the argument is always *thisthread*
    Example (time *thisthread*)

    Updated 29/11/2008 Copyright © 2008 Walther Waeles
    SourceForge.net Logo