dagger.releasablereferences.ReleasableReferenceManager Maven / Gradle / Ivy
Show all versions of dagger Show documentation
/*
* Copyright (C) 2016 The Dagger Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package dagger.releasablereferences;
import dagger.internal.Beta;
import dagger.internal.GwtIncompatible;
import java.lang.annotation.Annotation;
import java.lang.ref.WeakReference;
import javax.inject.Provider;
/**
* An object that can release or
* restore strong references held in a {@link CanReleaseReferences @CanReleaseReferences} scope.
*
* Your top-level component can provide a {@link
* ForReleasableReferences @ForReleasableReferences(Foo.class)} {@link ReleasableReferenceManager}
* object for any {@link CanReleaseReferences @CanReleaseReferences}-annotated scope {@code Foo}
* anywhere in your component hierarchy.
*
*
It can also provide a {@code Set} that contains all such objects.
*
* Each provider in the {@link CanReleaseReferences @CanReleaseReferences} {@link #scope()} can
* be in any one of four states at a time:
*
*
* - In uninitialized state, the provider's strong reference and its {@link
* WeakReference} are both {@code null}.
*
- In cleared state, the provider's strong reference is {@code null}, and its {@link
* WeakReference}'s value is {@code null}.
*
- In strong-reference state, the provider's strong reference refers to the cached
* value, and its {@link WeakReference} is {@code null}.
*
- In weak-reference state, the provider's strong reference is {@code null}, and its
* {@link WeakReference}'s value is not {@code null}.
*
*
* All providers within {@link #scope()} start in uninitialized state.
*
*
Calling {@link Provider#get()} on a provider within {@link #scope()} transitions it to
* strong-reference state if it was in uninitialized or empty state.
*
*
{@link #releaseStrongReferences()} transitions all providers within {@link #scope()} that are
* in strong-reference state to weak-reference state.
*
*
{@link #restoreStrongReferences()} transitions all providers within {@link #scope()} that are
* in weak-reference state to strong-reference state.
*
*
If garbage collection clears the {@link WeakReference} for any provider within {@link
* #scope()} that is in weak-reference state, that provider transitions to cleared
* state.
*
*
*
*
This interface is implemented by Dagger.
*
* @since 2.8
*/
@Beta
@GwtIncompatible
public interface ReleasableReferenceManager {
/** The scope whose references are managed by this object. */
Class scope();
/**
* Releases the strong references held by all providers in this {@linkplain #scope() scope} to the
* objects previously returned by {@link Provider#get()}, leaving only {@link WeakReference}s.
*
*
If any such {@link WeakReference} is cleared during garbage collection, the next call to
* that {@link Provider#get()} will execute the underlying binding again, and the provider will
* hold a strong reference to the new returned value.
*
*
Calls to {@link Provider#get()} on any such provider return the weakly-referenced object
* until the {@link WeakReference} is cleared or {@link #restoreStrongReferences()} is called.
*/
void releaseStrongReferences();
/**
* Restores strong references for all providers in this {@linkplain #scope() scope} that were
* previously {@linkplain #releaseStrongReferences() released} but whose {@link WeakReference} has
* not yet been cleared during garbage collection.
*/
void restoreStrongReferences();
}