android - Dagger2 Custom Scopes : How do custom-scopes (@ActivityScope) actually work?

Question

I am reading the source code for Dagger2 Component Scopes Test on GitHub, and I've seen a "custom scope" defined for activities called @ActivityScope, but I've seen it in other projects including the 4-module CleanArchitecture that has its @PerActivity scope.

But literally, the code for the @ActivityScope annotation is the following:

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

import javax.inject.Scope;

/**
 * Created by joesteele on 2/15/15.
 */
@Scope
@Retention(RetentionPolicy.RUNTIME)
public @interface ActivityScope {
}

And it is "magically" usable in Modules:

@Module
public class ActivityModule {
  @Provides @ActivityScope Picasso providePicasso(ComponentTest app, OkHttpClient client) {
    return new Picasso.Builder(app)
        .downloader(new OkHttpDownloader(client))
        .listener(new Picasso.Listener() {
          @Override public void onImageLoadFailed(Picasso picasso, Uri uri, Exception e) {
            Log.e("Picasso", "Failed to load image: " + uri.toString(), e);
          }
        })
        .build();
  }
}

Or the CleanArchitecture example:

@Scope
@Retention(RUNTIME)
public @interface PerActivity {}

@PerActivity
@Component(dependencies = ApplicationComponent.class, modules = ActivityModule.class)
public interface ActivityComponent {
  //Exposed to sub-graphs.
  Activity activity();
}

@Module
public class ActivityModule {
  private final Activity activity;

  public ActivityModule(Activity activity) {
    this.activity = activity;
  }

  /**
  * Expose the activity to dependents in the graph.
  */
  @Provides @PerActivity Activity activity() {
    return this.activity;
  }
}

I can clearly see that this has to do with JSR-330 custom scopes, but I really don't understand what exactly is happening here to make it so that this code enables the given module and/or what is provided by a given module to depend on the actual Activity lifecycle, and for there to exist only a single instance but only if that given activity is active.

The docs say this:

Scope

Dagger 1 only supported a single scope: @Singleton. 
Dagger 2 allows users to any well-formed scope annotation. 
The Component docs describe the details of 
    how to properly apply scope to a component.

It says to look at the Component docs page, but that gives me 404. I also saw this, but...

May I ask for some help in clarifying why specifying this custom scope magically makes Activity-level scopes work without an issue?

(The answer is, a subscope can receive dependencies from its superscope, and a subscope exists as long as the component does. And that you need to specify the scopes on your modules, and you need to specify your component dependencies to subscope one superscope.)

Answer 1

Actually there is no magic. Custom scope annotations are just annotations. They can have any name.

First function of scopes is a way to tell Dagger compiler which scopes are allowed within scoped component. That's why using @ActivityScope dependency in non-@ActivityScope component will fire a compilation error.

In fact components can declare many scopes (e.g. @ActivityScope and @UiScope) and Dagger will treat both of them as single scope - it's called scope aliasing. For example, it's useful in multi module projects - when one Gradle module defines one scope with its Dagger modules and another Gradle module defines another scope, while both of them can be used as single aliased scope in some third Gradle module that defines Dagger component.

Second function is to limit number of instances allowed within scoped component. There are several types of scopes supported:

Unscoped - when no annotation declared. Unscoped dependency will have simple Provider generated without any caching and any instance of that dependency created in component will be new for every new injection (as in constructor, or in module provision method, or just as a field).

Custom scope e.g. @ActivityScope annotation defined with @javax.inject.Scope annotation - Dependencies declared with that scope with have caching Provider with double-check lock generated and only single instance will be created for it within component declared with the same scope and its creation will be thread safe. Note that for every instance of component itself new instance of that dependency will be created.

Reusable scope - declared with @dagger.Reusable annotation - Dependencies declared with that scope may be shared between different components through common parent component and will have caching Provider with single-check lock generated. It is useful when dependency does not necessarily need to have single instance but may be shared for increased performance (less allocations) in single component or between components.

For more info on how scopes work refer to user's guide and Dagger's generated code.

How to define the actual scope is your prerogative. Define the livecycle of your scope component, when it's created and when it destroyed - this is your scope. E.g. @ActivityScope is tied to Activity livecycle and defined like that:

private ActivityComponent component;

@Override
protected void onCreate(Bundle savedInstanceState) {
    component = DaggerActivityComponent.builder().build();
    component.inject(this);
}

@Override
protected void onDestroy() {
    component = null;
    super.onDestroy();
}

So there is no magic. Define your scopes by the semantics of using them. You may also find useful this answer and these examples.

EDIT 14.10.2018 Expanded on scopes functions and types to eliminate ambiguity in previous answer.