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