ThreadService maintains references to all JRuby-specific thread data structures needed for Ruby's threading API and for JRuby's execution. The main structures are:

ThreadContext, which contains frames, scopes, etc needed for Ruby execution
RubyThread, the Ruby object representation of a thread's state
RubyThreadGroup, which represents a group of Ruby threads
RubyNativeThread, used to wrap threads owned by the current Ruby runtime
AdoptedNativeThread, used to wrap threads managed outside of JRuby

In order to ensure these structures do not linger after the thread has terminated, most of them are either weakly or softly referenced. The references associated with these structures are:

ThreadService is itself a ThreadLocal, which holds a soft reference to a ThreadContext. So the thread's locals softly reference ThreadContext. We use a soft reference to keep ThreadContext instances from going away too quickly when a Java thread leaves Ruby space completely, which would otherwise result in a lot of ThreadContext object churn.
ThreadService maintains a weak map from the actual java.lang.Thread instance to the associated RubyThread. The map is weak-keyyed, so it will not prevent the collection of the associated Thread. The associated RubyThread will remain alive as long as the Thread and this ThreadService instance are both alive, maintaining the external thread's identity in Ruby-land.
RubyThread has a weak reference to its to ThreadContext.
ThreadContext has a hard reference to its associated RubyThread. Ignoring other references, this will usually mean RubyThread is softly reachable via the soft threadlocal reference to ThreadContext in ThreadService.
RubyThreadGroup has hard references to threads it owns. The thread removes itself on termination (if it's a Ruby thread) or when the ThreadContext is collected (as in the case of "adopted" Java threads.

These data structures can come to life in one of two ways:

A Ruby thread is started. This constructs a new RubyThread object, which calls to ThreadService to initialize a ThreadContext and appropriate mappings in all ThreadService's structures. The body of the thread is wrapped with a finally block that will forcibly unregister the thread and all related structures from ThreadService.
A Java thread enters Ruby by doing a call. The thread is "adopted", and gains a RubyThread instance, a ThreadContext instance, and all associated mappings in ThreadService. Since we don't know when the thread has "left" Ruby permanently, no forcible unregistration is attempted for the various structures and maps. However, they should not be hard-rooted; the ThreadContext is only softly reachable at best if no calls are in-flight, so it will collect. Its collection will release the reference to RubyThread, and its finalizer will unregister that RubyThread from its RubyThreadGroup. With the RubyThread gone, the Thread-to-RubyThread map will eventually clear, releasing the hard reference to the Thread itself.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	ThreadService.Event Deprecated

Modifier and Type	Field and Description
private final ReentrantLock	criticalLock
private ThreadContext	mainContext A hard reference to the "main" context, so we always have one waiting for "main" thread execution.
private final ThreadGroup	rubyThreadGroup The Java thread group into which we register all Ruby threads.
private final Map<Thread, RubyThread>	rubyThreadMap A map from a Java Thread to its RubyThread instance.
private final Ruby	runtime
private final AtomicLong	threadCount

Constructor Summary

Access	Constructor and Description
public	ThreadService(final Ruby runtime)

Method Summary

Modifier and Type	Method and Description
private void	acquireCritical() Deprecated
private RubyThread	adoptCurrentThread()
private static ThreadContext	adoptLoop(ThreadService service)
public void	associateThread(Thread thread, RubyThread rubyThread)
private static ThreadContext	contextFromAdopt(ThreadService service)
public void	deliverEvent(RubyThread sender, RubyThread target, ThreadService.Event event) Deprecated
public void	disposeCurrentThread() Deprecated
public synchronized void	dissociateThread(Object thread) Deprecated
public RubyThread[]	getActiveRubyThreads()
public boolean	getCritical() Deprecated
public final ThreadContext	Returns: The ThreadContext instance for the current thread, or a new one if none has previously been created or the old ThreadContext has been collected. getCurrentContext() In order to provide an appropriate execution context for a given thread, we store ThreadContext instances in a threadlocal.
public static ThreadContext	getCurrentContext(final ThreadService service)
public RubyThread	getMainThread()
public boolean	getPolling() Deprecated
public ThreadGroup	getRubyThreadGroup() Deprecated
public Map<Object, RubyThread>	getRubyThreadMap() Deprecated
public ThreadContext	getThreadContextForThread(RubyThread thread) Deprecated
public long	incrementAndGetThreadCount()
public void	initMainThread()
public ThreadContext	registerNewThread(RubyThread thread)
private void	releaseCritical() Deprecated
public void	setCritical(boolean critical) Deprecated
public final void	setCurrentContext(ThreadContext context) Deprecated
public void	setMainThread(Thread thread, RubyThread rubyThread)
public void	teardown()
public void	unregisterCurrentThread(ThreadContext context)
public void	unregisterThread(RubyThread thread)
private void	unregisterThreadImpl(ThreadContext context, Thread nativeThread)

Inherited from java.lang.ThreadLocal:: get initialValue remove set withInitial

criticalLock	back to summary
private final ReentrantLock criticalLock

mainContext	back to summary
private ThreadContext mainContext A hard reference to the "main" context, so we always have one waiting for "main" thread execution.

rubyThreadGroup	back to summary
private final ThreadGroup rubyThreadGroup The Java thread group into which we register all Ruby threads. This is distinct from the RubyThreadGroup, which is simply a mutable collection of threads.

rubyThreadMap	back to summary
private final Map<Thread, RubyThread> rubyThreadMap A map from a Java Thread to its RubyThread instance. This is a synchronized WeakHashMap, so it weakly references its keys; this means that when the Thread goes away, eventually its entry in this map will follow.

runtime	back to summary
private final Ruby runtime

threadCount	back to summary
private final AtomicLong threadCount

Constructor Detail

ThreadService	back to summary
public ThreadService(final Ruby runtime)

Method Detail

acquireCritical	back to summary
private void acquireCritical() Deprecated Annotations @Deprecated

adoptCurrentThread	back to summary
private RubyThread adoptCurrentThread()

adoptLoop	back to summary
private static ThreadContext adoptLoop(ThreadService service)

associateThread	back to summary
public void associateThread(Thread thread, RubyThread rubyThread)

contextFromAdopt	back to summary
private static ThreadContext contextFromAdopt(ThreadService service)

deliverEvent	back to summary
public void deliverEvent(RubyThread sender, RubyThread target, ThreadService.Event event) Deprecated Annotations @Deprecated

disposeCurrentThread	back to summary
public void disposeCurrentThread() Deprecated Annotations @Deprecated

dissociateThread	back to summary
public synchronized void dissociateThread(Object thread) Deprecated Annotations @Deprecated

getActiveRubyThreads	back to summary
public RubyThread[] getActiveRubyThreads()

getCritical	back to summary
public boolean getCritical() Deprecated Annotations @Deprecated

getCurrentContext	back to summary
public final ThreadContext getCurrentContext() In order to provide an appropriate execution context for a given thread, we store ThreadContext instances in a threadlocal. This method is a utility to get at that threadlocal context from anywhere in the program it may not be immediately available. This method should be used sparingly, and if it is possible to pass ThreadContext on the argument list, it is preferable. Description of behavior The threadlocal does not actually contain the ThreadContext directly; instead, it contains a SoftReference that holds the ThreadContext. This is to allow new threads to enter the system and execute Ruby code with a valid context, but still allow that context to garbage collect if the thread stays alive much longer. We use SoftReference here because WeakReference is collected too quickly, resulting in very expensive ThreadContext churn (and this originally lead to JRUBY-2261's leak of adopted RubyThread instances). Returns:ThreadContext The ThreadContext instance for the current thread, or a new one if none has previously been created or the old ThreadContext has been collected.

getCurrentContext

back to summary

public final ThreadContext getCurrentContext()

In order to provide an appropriate execution context for a given thread, we store ThreadContext instances in a threadlocal. This method is a utility to get at that threadlocal context from anywhere in the program it may not be immediately available. This method should be used sparingly, and if it is possible to pass ThreadContext on the argument list, it is preferable. Description of behavior The threadlocal does not actually contain the ThreadContext directly; instead, it contains a SoftReference that holds the ThreadContext. This is to allow new threads to enter the system and execute Ruby code with a valid context, but still allow that context to garbage collect if the thread stays alive much longer. We use SoftReference here because WeakReference is collected too quickly, resulting in very expensive ThreadContext churn (and this originally lead to JRUBY-2261's leak of adopted RubyThread instances).

Returns:ThreadContext: The ThreadContext instance for the current thread, or a new one if none has previously been created or the old ThreadContext has been collected.

getCurrentContext	back to summary
public static ThreadContext getCurrentContext(final ThreadService service)

getMainThread	back to summary
public RubyThread getMainThread()

getPolling	back to summary
public boolean getPolling() Deprecated Annotations @Deprecated

getRubyThreadGroup	back to summary
public ThreadGroup getRubyThreadGroup() Deprecated Annotations @Deprecated

getRubyThreadMap	back to summary
public Map<Object, RubyThread> getRubyThreadMap() Deprecated Annotations @Deprecated

getThreadContextForThread	back to summary
public ThreadContext getThreadContextForThread(RubyThread thread) Deprecated Annotations @Deprecated

incrementAndGetThreadCount	back to summary
public long incrementAndGetThreadCount()

initMainThread	back to summary
public void initMainThread()

registerNewThread	back to summary
public ThreadContext registerNewThread(RubyThread thread)

releaseCritical	back to summary
private void releaseCritical() Deprecated Annotations @Deprecated

setCritical	back to summary
public void setCritical(boolean critical) Deprecated Annotations @Deprecated

setCurrentContext	back to summary
public final void setCurrentContext(ThreadContext context) Deprecated Annotations @Deprecated

setMainThread	back to summary
public void setMainThread(Thread thread, RubyThread rubyThread)

teardown	back to summary
public void teardown()

unregisterCurrentThread	back to summary
public void unregisterCurrentThread(ThreadContext context)

unregisterThread	back to summary
public void unregisterThread(RubyThread thread)

unregisterThreadImpl	back to summary
private void unregisterThreadImpl(ThreadContext context, Thread nativeThread)

org.jruby.internal.runtime back to summary

public Class ThreadService.Event

Class Inheritance

extends Object

java.lang.Object
org.jruby.internal.runtime.ThreadService.Event

Annotations

@Deprecated

Deprecated

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	ThreadService.Event.Type

Field Summary

Modifier and Type	Field and Description
public final String	description
public final IRubyObject	exception
public final ThreadService.Event.Type	type

Constructor Summary

Access	Constructor and Description
public	Event(String description, ThreadService.Event.Type type)
public	Event(String description, ThreadService.Event.Type type, IRubyObject exception)

Method Summary

Modifier and Type	Method and Description
public static ThreadService.Event	kill(RubyThread sender, RubyThread target, ThreadService.Event.Type type) Deprecated
public static ThreadService.Event	raise(RubyThread sender, RubyThread target, ThreadService.Event.Type type, IRubyObject exception) Deprecated
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
public static ThreadService.Event	wakeup(RubyThread sender, RubyThread target, ThreadService.Event.Type type) Deprecated

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

description	back to summary
public final String description

exception	back to summary
public final IRubyObject exception

type	back to summary
public final ThreadService.Event.Type type

Constructor Detail

Event	back to summary
public Event(String description, ThreadService.Event.Type type)

Event	back to summary
public Event(String description, ThreadService.Event.Type type, IRubyObject exception)

Method Detail

kill	back to summary
public static ThreadService.Event kill(RubyThread sender, RubyThread target, ThreadService.Event.Type type) Deprecated Annotations @Deprecated

raise	back to summary
public static ThreadService.Event raise(RubyThread sender, RubyThread target, ThreadService.Event.Type type, IRubyObject exception) Deprecated Annotations @Deprecated

toString back to summary

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String: a string representation of the object

wakeup	back to summary
public static ThreadService.Event wakeup(RubyThread sender, RubyThread target, ThreadService.Event.Type type) Deprecated Annotations @Deprecated

org.jruby.internal.runtime back to summary

public final Enum ThreadService.Event.Type

Class Inheritance

extends Enum<ThreadService.Event.Type>

java.lang.Object
java.lang.Enum
org.jruby.internal.runtime.ThreadService.Event.Type

Field Summary

Modifier and Type	Field and Description
public static final ThreadService.Event.Type	KILL
public static final ThreadService.Event.Type	RAISE
public static final ThreadService.Event.Type	WAKEUP

Constructor Summary

Access	Constructor and Description
private	Type()

Method Summary

Modifier and Type	Method and Description
public static ThreadService.Event.Type	valueOf(String name)
public static ThreadService.Event.Type[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

KILL	back to summary
public static final ThreadService.Event.Type KILL

RAISE	back to summary
public static final ThreadService.Event.Type RAISE

WAKEUP	back to summary
public static final ThreadService.Event.Type WAKEUP

Constructor Detail

Type	back to summary
private Type()

Method Detail

valueOf	back to summary
public static ThreadService.Event.Type valueOf(String name)

values	back to summary
public static ThreadService.Event.Type[] values()