Class Thread.Thread

Defined in: thread.jsdoc.

Class Summary
Constructor Attributes	Constructor Name and Description
	Thread.Thread(func) Exposes a threading API to JavaScript.

Field Summary
Field Attributes	Field Name and Description
<inner>	exception Uncaught exception which aborted the thread.
<inner>	state State of the thread.
<inner>	threadID Thread ID.
<static>	Thread.Thread.threadList List of running threads.

Method Summary
Method Attributes	Method Name and Description
<inner>	exit(exitCode) Terminate the current thread.
<static>	Thread.Thread.getcpuid() Retrieve the ID of the CPU the current thread is running on.
<inner>	join() Wait for a thread to join.
<inner>	run() Function which is run when thread is spawned.
<static>	Thread.Thread.sleep(seconds) Pause execution of the current thread.
<inner>	start() Start the thread.
<static>	Thread.Thread.yield() Yield execution of the current thread.

Class Detail

Thread.Thread(func)

Exposes a threading API to JavaScript.

As of SpiderMonkey 1.8, there are multithreaded property access "gotchas" to be aware of. While previous releases to serialized access to objects, new optimizations in the engine have changed this - particularly for arrays. It is recommended that inter-thread communication be limited to manipulating properties of the the thread handle (which appears to the running thread as "this" in its outermost scope), and only checking those values when the thread joins. If only one value needs to be exchanged, the safest way is to use the Thread.exit() method.

The Thread class uses the GPSEE multiplexed branch callback to periodically yield and sweep for joined threads. This should insure good concurrency and reasonable resource consumption, even in applications which spawn many threads from JavaScript.

Parameters:
func: Function to launch when thread is started.

Throws:
: gpsee.module.ca.page.thread.constructor.notFunction when constructor is called without new
: gpsee.module.ca.page.thread.constructor.arguments.count when argument count is wrong
: gpsee.module.ca.page.thread.constructor.arguments.0.typeOf when first argument is not a function

Returns:: Thread handle in new state

See:

https://developer.mozilla.org/en/JS_THREADSAFE

https://developer.mozilla.org/En/SpiderMonkey/Internals/Thread_Safety

The thread class uses the following GPSEE runtime configuration variables:

RC Variable	Default Value	Notes
gpsee_thread_stack_chunk_size	gpsee_stack_chunk_size RC variable or 8192	Stack chunk size for thread's context

Field Detail

<inner> exception

Uncaught exception which aborted the thread.

<inner> state

State of the thread. Possible values are:

new
runnable
joining
dead

Thread State Transition Diagram

void          new              runnable                joining        dead       Why
============================================================================================================
|---Thread----->                                                                 Constructor
               |--th_start-------->                                              About to start NSPR thread
                                  |-------------th_start---------------->        NSPR thread failed to start
                                  |--------thread_join--->                       Waiting on PR_JoinThread
                                                         |--thread_join->        Thread stopped running
               |----------------------Thread_Finalize------------------->        Still born (never ran)

Thread instance object is inserted into Thread.threadList when marked runnable
Thread instance object is removed from Thread.threadList when marked dead

<inner> threadID

Thread ID. A string unique to the current thread. May be re-used again by another thread once the current thread has died and its handle finalized.

<static> Thread.Thread.threadList

List of running threads. Has a length property.

Method Detail

<inner> exit(exitCode)

Terminate the current thread.

Parameters:
exitCode: Value to pass back in thread handle, through its exitCode property. This method Treats exiting the primordial thread the same as calling gpsee.module.ca.page.ca.system.exit(). Note that exiting the main thread will not cause the program to terminate immediately, it will still block waiting for all the other threads to join and THEN exit.

<static> Thread.Thread.getcpuid()

Retrieve the ID of the CPU the current thread is running on. Currently available only under Solaris.

Returns:: CPU ID

<inner> join()

Wait for a thread to join.

Blocks until either this thread (obj) has finished running, or it is discovered that this thread is not joinable (i.e. already joined, another thread trying to join, etc.)

All threads are created joinable, however it is not be possible to join a thread when:

the thread was never started
another thread is trying to join it
the thread is no longer running

Throws:
: gpsee.module.ca.page.thread.join.this when a thread tries to join itself.

Returns:: true when the thread was joined, false when it could not be joined

<inner> run()

Function which is run when thread is spawned. Normally assigned by constructor, not intended to be called directly, but rather by this.start();

<static> Thread.Thread.sleep(seconds)

Pause execution of the current thread.

Parameters:
seconds: Amount of time to sleep, accepts floats.

<inner> start()

Start the thread. Executes the this.run method in a new thread. No arguments are passed along; if the thread requires arguments from the parent, the parent should modify the thread handle and the running thread can check its outer-most 'this'.

<static> Thread.Thread.yield()

Yield execution of the current thread. Gives up the remainder of of the OS-scheduler-assigned timeslice and suspends the JSAPI request on the current thread's context.

Classes

Class Thread.Thread