JRuby Base 10.0.0.0 · org.jruby.embed.LocalContextScope

LocalContextState defines four scopes to maintain LocalContext.

A single ScriptingContainer can be configured to act as a facade for multiple Ruby runtimes (or really multiple Ruby VMs, since each Ruby instance is a Ruby "VM"), and this enum controls that behaviour. (this behaviour is bit like that of ThreadLocal — it changes its behaviour silently depending on the calling thread, an act of multiplexing.)

When you think of this multiplexing behaviour, there are two sets of states that need separate attention. One is Ruby instance, which represents the whole VM, classes, global variables, etc. Then there's attributes and so-called variables, which are really a special scope induced by the scripting container for better JSR-223 interop. In this documentation, we refer to the former as "the runtime" and the latter as "the variables", but the variables shouldn't be confused with the global variables in Ruby's semantics, which belongs to the runtime.

Modifier and Type	Field and Description
public static final LocalContextScope	CONCURRENT Use a single runtime but variable maps are thread local.
public static final LocalContextScope	SINGLETHREAD `ScriptingContainer` will not do any multiplexing at all.
public static final LocalContextScope	SINGLETON Uses a "global" singleton runtime and variables.
public static final LocalContextScope	THREADSAFE Maintain separate runtimes and variable maps for each calling thread.

Access	Constructor and Description
private	LocalContextScope()

Modifier and Type	Method and Description
public static LocalContextScope	valueOf(String name)
public static LocalContextScope[]	values()

Field Detail

CONCURRENT back to summary

CONCURRENT	back to summary
public static final LocalContextScope CONCURRENT Use a single runtime but variable maps are thread local. In this mode, there'll be a single runtime dedicated for each `ScriptingContainer`, but a separate map of variables are created for each calling thread through `ThreadLocal`. In a situation where you have multiple threads calling one `ScriptingContainer`, this means ruby code will see multiple threads calling them, and therefore they need to be thread safe. But because variables are thread local, if your program does something like (1) set a few variables, (2) evaluate a script that refers to those variables, then you won't have to worry about values from multiple threads mixing with each other.

public static final LocalContextScope CONCURRENT

Use a single runtime but variable maps are thread local.

In this mode, there'll be a single runtime dedicated for each ScriptingContainer, but a separate map of variables are created for each calling thread through ThreadLocal. In a situation where you have multiple threads calling one ScriptingContainer, this means ruby code will see multiple threads calling them, and therefore they need to be thread safe. But because variables are thread local, if your program does something like (1) set a few variables, (2) evaluate a script that refers to those variables, then you won't have to worry about values from multiple threads mixing with each other.

SINGLETHREAD back to summary

SINGLETHREAD	back to summary
public static final LocalContextScope SINGLETHREAD `ScriptingContainer` will not do any multiplexing at all. `ScriptingContainer` will get one runtime and one set of variables, and regardless of the calling thread it'll use this same pair. If you have multiple threads calling single `ScriptingContainer` instance, then you may need to take caution as a variable set by one thread will be visible to another thread. If you aren't using the variables of `ScriptingContainer`, this is normally what you want.

public static final LocalContextScope SINGLETHREAD

ScriptingContainer will not do any multiplexing at all.

ScriptingContainer will get one runtime and one set of variables, and regardless of the calling thread it'll use this same pair.

If you have multiple threads calling single ScriptingContainer instance, then you may need to take caution as a variable set by one thread will be visible to another thread.

If you aren't using the variables of ScriptingContainer, this is normally what you want.

SINGLETON back to summary

SINGLETON	back to summary
public static final LocalContextScope SINGLETON Uses a "global" singleton runtime and variables. All the `ScriptingContainer`s that are created with this scope will share a single runtime and a single set of variables. Therefore one container can `set a value` and another container will see the same value. The global runtime comes from `org.jruby.Ruby#getGlobalRuntime()`, which initializes or retrieves a Ruby instance in a static field on `org.jruby.Ruby`. All singleton context scopes will reuse this instance. When any singleton-based scripting container is torn down (`ScriptingContainer#terminate()`), the global runtime will also be torn down and cleared. Subsequent singleton containers will see a new runtime. Note that unlike the other modes, containers created with singleton context scoping will not tear down the associated JRuby runtime upon finalization.

public static final LocalContextScope SINGLETON

Uses a "global" singleton runtime and variables. All the ScriptingContainers that are created with this scope will share a single runtime and a single set of variables. Therefore one container can set a value and another container will see the same value. The global runtime comes from org.jruby.Ruby#getGlobalRuntime(), which initializes or retrieves a Ruby instance in a static field on org.jruby.Ruby. All singleton context scopes will reuse this instance. When any singleton-based scripting container is torn down (ScriptingContainer#terminate()), the global runtime will also be torn down and cleared. Subsequent singleton containers will see a new runtime. Note that unlike the other modes, containers created with singleton context scoping will not tear down the associated JRuby runtime upon finalization.

THREADSAFE back to summary

THREADSAFE	back to summary
public static final LocalContextScope THREADSAFE Maintain separate runtimes and variable maps for each calling thread. Known as the "apartment thread model", this mode makes `ScriptingContainer` lazily creates a runtime and a variable map separately for each calling thread. Therefore, despite the fact that multiple threads call on the same object, they are completely isolated from each other. (the flip side of the coin is that no ruby objects can be shared between threads as they belong to different "ruby VM".)

public static final LocalContextScope THREADSAFE

Maintain separate runtimes and variable maps for each calling thread.

Known as the "apartment thread model", this mode makes ScriptingContainer lazily creates a runtime and a variable map separately for each calling thread. Therefore, despite the fact that multiple threads call on the same object, they are completely isolated from each other. (the flip side of the coin is that no ruby objects can be shared between threads as they belong to different "ruby VM".)

public final Enum LocalContextScope

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail