TP 3 Draft Specs

[stephanenicolas]

This issue is a central hub for the specifications of TP 3. It can refer to more detailed issues but should offer a summary of the features we plan for the next major release of TP.

Releasable singletons

We should release all internal providers under memory pressure, but not automatically as some can't recover their state. Thus, users should have full control over this. We should provide different mechanisms to let user mark classes whose singletons can be released:

• add an annotation @releasable that can apply to a type that is injected
• add .markAsReleasable() to the bindings API

Details in #212

Better scope annotations

For now, only "singleton classes" can be annotated to indicate in which scope TP should create an instance of theses classes. We want to extend this mechanism, which actually breaks the JSR 330, and allows things like:

@ActivityScope 
public class Foo {}

Which means Foo can only be created by TP inside a scope that supports the @ActivityScope, but without Foo being a singleton. A singleton would be expressed by:

@ActivityScope  @Singleton
public class FooSingleton {}

Note that this new notation is just making more clear and distinct to which scope entities belong and how they are recycled. These 2 concepts are currently entangled in JSR 330. Also, using the new annotation model will still preserve the strong contract of

@Singleton
public class FooSingleton {}

being a singleton of the root scope, as everyone would expect.

This change should not require any binding API changes.

Better TP API

Changing the API will also help users to be sure of which TP version they are using and avoid misinterpreting the new annotation model.

• Toothpick.inject(foo, scope) --> scope.inject(foo), more details in Change scope API to allow a scope to inject #217.
• give scopes a fluent API, more details in Change scope to have a builder API for some methods #218.
• change bind --> support for scope annotation, more details in change bind --> support for scope annotation  #169
• allow to inject package-protected classes, right now we only allow public Let TP use injection on non public classes #227 (testEmptyConstructor_shouldWork_whenConstructorIsProtected)
• allow @Inject annotated methods to send Exceptions, more details in Allow @Inject annotated methods to send Exceptions  #200
• give a base class to factories and MemberInjectors? to limit the generated code size (Create base class for Factories and MI? #347).

Improve Examples

• Fix Test examples by using ToothpickRule
• Add a @singleton example
• Add Presenter and Flow example (state preservation)
• Improve coding style in examples -> inner classes, bad names, ...
• Make sure all examples work (toothpick-sample tests are failing #337)

KTP

#316

Documentation

• Improve documentation and come with a way to represent the way it works internally for maintainers.

Misc

• Add test to make sure that releasable is working
• Add test to verify that the new scope and singleton system works
• Add tests to make sure that the whole library works for Kotlin
• Add support for Mockk (Tests with Mockk #334)
• Being able to test scope graph at build time using unit tests (test scope graph at build time using unit tests #348)
• switch to Mockito internally
• make scopes lifecycle-aware (Support for reactive API #332)

other ideas

Add an annotation @ShouldBeLazy so that a class can only be injected lazily. This could help for instance to delay the creation of some network related classes..

[ultimate-deej]

Let me share my thoughts on it.

1. Releasable singletons.

   tldr: I doubt this is something a DI library should do.

   Detailed explanation
   I'm strongly against this. This will introduce more complexity with little to no benefits. If user needs to handle low memory conditions they should do it solely on their own without resorting to a DI library. After all, Toothpick is a dependency injection library, not a memory management library. Finally, this will make singletons not so singletons.

2. Better scope annotations. Love it! Will definitely give more control and make things clearer. As for JSR 330, I don't think it will break the standard (emphasis mine):

   If a scope annotation is present, the injector may retain the instance for possible reuse in a later injection

   However, it might in fact cause confusion to users.

3. The rest looks 👍, except that it is unclear to me what change bind --> support for scope annotation  #169 is about

[stephanenicolas]

@ultimate-deej

1. TP has an impact on memory as it keeps singletons. We want to offer the option to release them which I believe would have a very positive impact on apps. Of course, it's up to users of TP to make things releasable and they have to make sure their releasable singletons will work well when destroyed and recreated (basically load/save state on the file system).
   And yes, it will make singletons not so singletons and it's exactly what we want and will explain in the docs.
2. we would still break the JSR 330 in one way: @singleton in the JSR 330 is a 'scope' annotation. It means 2 things at the same: the instance should be reused across injection sites and it belongs to the root scope. In TP3, we want to distinguish this 2 things and make it possible to do things such as @ActivityScope @Singleton and @ActivityScope only. So we can distinguish basically the scope a class should belong to and the fact that it's instance is reused. And this is a difference from JSR 330.
3. change bind --> support for scope annotation  #169 is just about naming: we bind an interface/class to its implementation in a module and we also bind custom scope annotations. We want to distinguish these 2 very different things. The second operation will be renamed to supporting a custom scope.

[ultimate-deej]

1. Are you talking about the overhead created by TP, or just about the fact that long-living objects consume memory? If it is the former case, how significant is it? If it is the latter, again, the user is responsible and there is no need to aid him in this. You might also consider the dagger's team experience Do you use ReleasableReferences?  google/dagger#1117, they have dropped a similar feature.
2. Yeah, didn't think of that. What if you leave @Singleton intact, thus keeping compliance to the standard, and instead create a custom annotation similar to @ProvidesSingletonInScope? Like @SingletonInScope for instance. This would clearly indicate that it's not standard as well as better communicate the intent (because of a little more verbosity).
3. Thx for the explanation!

[stephanenicolas]

1. No there is no significant overhead, I am talking about the ability to remove these long living objects.
   Unfortunately, users can't release them. TP 1/2 offers Singletons that can't be released, we will offer releasable ones as well.
   Thx for the dagger thread about the removal, I didn't know about that. The main reason they want to get rid of this is for decreasing complexity. Let's see what it gives in TP, but at Groupon,we have quite some use cases for this. I believe the implementation is simpler for TP.
2. We are really looking for something clear and intuitive, not sure yours is ;) Also, we will preserve the very essential contract of '@singleton' annotated classes. What will change is how custom Scopes are used.

[ultimate-deej]

1. Correct, the users can't release the objects themselves. What they can release is resources these long-living objects use. Any internal stuff they hold. But anyway, I said what I had to say so my job seems to be done here * flies away *.

BTW, why nobody else has commented on this? This topic needs discussion, for the good of this fantastic library.

[L7ColWinters]

I really like the idea of releasable singletons with an annotation since our team wanted to increase the performance of tp by caching classes that had no state but these "singletons" could be cleaned out and recreated since we only made it singleton to speed up the injection. Basically lazy garbage collection.

[stephanenicolas]

TODO: better CHANGELOG, README, and wiki landing page. To be updated for TP3.

[stephanenicolas]

Ticket closed as all was released in 3.0.0