public class SingletonScope extends java.lang.Object implements Scope
Injector
. Also see @
Singleton
.
Introduction from the author:
Implementation of this class seems unreasonably complicated at the first sight.
I fully agree with you, that the beast below is very complex
and it's hard to reason on how does it work or not.
Still I want to assure you that hundreds(?) of hours were thrown
into making this code simple, while still maintaining Singleton contract.
Anyway, why is it so complex? Singleton scope does not seem to be that unique.
1) Guice has never truly expected to be used in multi threading environment
with many Injectors working alongside each other. There is almost no
code with Guice that propagates state between threads. And Singleton
scope is The exception.
2) Guice supports circular dependencies and thus manages proxy objects.
There is no interface that allows user defined Scopes to create proxies,
it is expected to be done by Guice. Singleton scope needs to be
able to detect circular dependencies spanning several threads,
therefore Singleton scope needs to be able to create these proxies.
3) To make things worse, Guice has a very tricky definition for a binding
resolution when Injectors are in in a parent/child relationship.
And Scope does not have access to this information by design,
the only real action that Scope can do is to call or not to call a creator.
4) There is no readily available code in Guice that can detect a potential
deadlock, and no code for handling dependency cycles spanning several threads.
This is significantly harder as all the dependencies in a thread at runtime
can be represented with a list, where in a multi threaded environment
we have more complex dependency trees.
5) Guice has a pretty strong contract regarding Garbage Collection,
which often prevents us from linking objects directly.
So simple domain specific code can not be written and intermediary
id objects need to be managed.
6) Guice is relatively fast and we should not make things worse.
We're trying our best to optimize synchronization for speed and memory.
Happy path should be almost as fast as in a single threaded solution
and should not take much more memory.
7) Error message generation in Guice was not meant to be used like this and to work around
its APIs we need a lot of code. Additional complexity comes from inherent data races
as message is only generated when failure occurs on proxy object generation.
Things get ugly pretty fast.scope(Key, Provider)
,
CycleDetectingLock
Modifier and Type | Field and Description |
---|---|
(package private) static java.lang.ThreadLocal<java.lang.ref.WeakReference<InjectorImpl>> |
currentInjector
SingletonScope needs the owning injector's thread-specific InternalContext object during
singleton instantiation, to look up type information on the singleton instance, and to
determine whether circular proxy creation is enabled within InjectorOptions.
|
private static CycleDetectingLock.CycleDetectingLockFactory<Key<?>> |
cycleDetectingLockFactory
Allows us to detect when circular proxies are necessary.
|
private static java.util.concurrent.ConcurrentMap<java.lang.Thread,InternalContext> |
internalContextsMap
A map of thread running singleton instantiation, to the InternalContext that is relevant
to the singleton being instantiated.
|
private static java.lang.Object |
NULL
A sentinel value representing null.
|
Constructor and Description |
---|
SingletonScope() |
Modifier and Type | Method and Description |
---|---|
<T> Provider<T> |
scope(Key<T> key,
Provider<T> creator)
Provides singleton scope with the following properties:
- creates no more than one instance per Key as a creator is used no more than once,
- result is cached and returned quickly on subsequent calls,
- exception in a creator is not treated as instance creation and is not cached,
- creates singletons in parallel whenever possible,
- waits for dependent singletons to be created even across threads and when dependencies
are shared as long as no circular dependencies are detected,
- returns circular proxy only when circular dependencies are detected,
- aside from that, blocking synchronization is only used for proxy creation and initialization,
|
java.lang.String |
toString()
A short but useful description of this scope.
|
private static final java.lang.Object NULL
static final java.lang.ThreadLocal<java.lang.ref.WeakReference<InjectorImpl>> currentInjector
InjectorImpl.callInContext(com.google.inject.internal.ContextualCallable<T>)
.
A thread-specific reference to the owning injector is stored here, so that the singleton
provider can access the correct InternalContext for the given thread during provider.get().
The ThreadLocal stores WeakReference, so that the references here and inside the singleton
provider do not interfere with garbage collection and post-collection cleanup of child
injectors, happening in WeakKeySet
.private static final java.util.concurrent.ConcurrentMap<java.lang.Thread,InternalContext> internalContextsMap
private static final CycleDetectingLock.CycleDetectingLockFactory<Key<?>> cycleDetectingLockFactory
Key
s as a user locks ids, different injectors can
share them. Cycles are detected properly as cycle detection does not rely on user locks ids,
but error message generated could be less than ideal.
TODO(user): we may use one factory per injector tree for optimization reasonspublic <T> Provider<T> scope(Key<T> key, Provider<T> creator)
scope
in interface Scope
key
- binding keycreator
- locates an instance when one doesn't already exist in this
scope.CycleDetectingLock.CycleDetectingLockFactory
public java.lang.String toString()
Scope
"Scopes.SINGLETON"
, "ServletScopes.SESSION"
and
"ServletScopes.REQUEST"
.