Change LifecycleCoroutineScope argument to a CoroutineContext, add Li…

…fecycleCoroutineScopeFactory (#145)

* change LifecycleCoroutineScope argument to CoroutineContext

* MainImmediateProvidedContext -> MainImmediateContext

* MainImmediateProvidedContext -> MainImmediateContext

* update docs

* MainImmediateProvidedContext -> MainImmediateContext

dispatch-android-espresso/samples/src/test/java/samples/IdlingCoroutineScopeRuleWithLifecycleSample.kt

@@ -39,9 +39,7 @@ class IdlingCoroutineScopeRuleWithLifecycleSample {
 
   @Before
   fun setUp() {
-    LifecycleScopeFactory.set {
-      MainImmediateCoroutineScope(customDispatcherProvider)
-    }
+    LifecycleScopeFactory.set { customDispatcherProvider }
     ViewModelScopeFactory.set {
       MainImmediateCoroutineScope(customDispatcherProvider)
     }

dispatch-android-lifecycle-extensions/README.md

@@ -51,7 +51,7 @@ class SomeApplication : Application() {
   override fun onCreate() {
     super.onCreate()
     // A custom factory can be set to add elements to the CoroutineContext
-    LifecycleScopeFactory.set { MainImmediateCoroutineScope() + SomeCustomElement() }
+    LifecycleScopeFactory.set { MainImmediateProvidedCoroutineContext() + SomeCustomElement() }
   }
 }
 ```
@@ -62,13 +62,13 @@ class SomeEspressoTest {
   fun setUp() {
     // This custom factory can be used to use custom scopes for testing,
     // such as an idling dispatcher
-    LifecycleScopeFactory.set { MainImmediateIdlingCoroutineScope() }
+    LifecycleScopeFactory.set { MainImmediateIdlingCoroutineScope().coroutineContext }
   }
 
   @After
   fun tearDown() {
     // The factory can also be reset to default
-    LifecycleScopeFactory.reset()
+    LifecycleCoroutineScopeFactory.reset()
   }
 }
 ```
@@ -93,7 +93,7 @@ class SomeFragmentEspressoTest {
   fun setUp() {
     // set a custom factory which is applied to all newly created lifecycleScopes
     LifecycleScopeFactory.set {
-      MainImmediateCoroutineScope() + idlingRule.dispatcherProvider
+      MainImmediateProvidedCoroutineContext() + idlingRule.dispatcherProvider
     }
 
     // now SomeFragment will use an IdlingDispatcher in its CoroutineScope

dispatch-android-lifecycle-extensions/api/dispatch-android-lifecycle-extensions.api

@@ -1,6 +1,7 @@
 public final class dispatch/android/lifecycle/LifecycleScopeFactory {
 	public static final field INSTANCE Ldispatch/android/lifecycle/LifecycleScopeFactory;
 	public final fun reset ()V
+	public final fun set (Ldispatch/android/lifecycle/LifecycleCoroutineScopeFactory;)V
 	public final fun set (Lkotlin/jvm/functions/Function0;)V
 }
 

dispatch-android-lifecycle-extensions/samples/src/test/java/samples/LifecycleScopeFactorySample.kt → dispatch-android-lifecycle-extensions/samples/src/test/java/samples/LifecycleCoroutineScopeFactorySample.kt

@@ -20,6 +20,7 @@ package samples
 import dispatch.android.espresso.*
 import dispatch.android.lifecycle.*
 import dispatch.core.*
+import kotlinx.coroutines.*
 
 class LifecycleScopeFactorySample {
 
@@ -29,7 +30,8 @@ class LifecycleScopeFactorySample {
     class MyApplication : Application {
 
       override fun onCreate() {
-        LifecycleScopeFactory.set { MainImmediateCoroutineScope() }
+
+        LifecycleScopeFactory.set { MyCustomElement() + MainImmediateContext() }
       }
     }
   }
@@ -41,19 +43,25 @@ class LifecycleScopeFactorySample {
 
       @Before
       fun setUp() {
-        LifecycleScopeFactory.set { MainImmediateIdlingCoroutineScope() }
+
+        val dispatcherProvider = IdlingDispatcherProvider()
+
+        LifecycleScopeFactory.set { SupervisorJob() + dispatcherProvider + dispatcherProvider.mainImmediate }
       }
     }
   }
 
   @Sample
-  fun lifecycleScopeFactoryResetSample() {
+  fun LifecycleScopeFactoryResetSample() {
 
     class MyEspressoTest {
 
       @Before
       fun setUp() {
-        LifecycleScopeFactory.set { MainImmediateIdlingCoroutineScope() }
+
+        val dispatcherProvider = DefaultDispatcherProvider()
+
+        LifecycleScopeFactory.set { SupervisorJob() + dispatcherProvider + dispatcherProvider.mainImmediate }
       }
 
       @After

dispatch-android-lifecycle-extensions/samples/src/test/java/samples/LifecycleCoroutineScopeSample.kt → dispatch-android-lifecycle-extensions/samples/src/test/java/samples/LifecycleScopeSample.kt

@@ -17,24 +17,11 @@ package samples
 
 import dispatch.android.lifecycle.*
 import dispatch.core.*
-import dispatch.test.*
-import kotlinx.coroutines.*
-import org.junit.jupiter.api.*
 
-@CoroutineTest
-@ExperimentalCoroutinesApi
-class LifecycleCoroutineScopeSample(
-  val testScope: TestProvidedCoroutineScope
-) {
-
-  @BeforeEach
-  fun beforeEach() {
-
-    LifecycleScopeFactory.set { testScope }
-  }
+class LifecycleScopeSample {
 
   @Sample
-  fun lifecycleCoroutineScopeSample() {
+  fun lifecycleScopeSample() {
 
     // This could be any LifecycleOwner -- Fragments, Activities, Services...
     class SomeFragment : Fragment() {

dispatch-android-lifecycle-extensions/src/main/java/dispatch/android/lifecycle/LifecycleScopeFactory.kt

@@ -18,45 +18,84 @@ package dispatch.android.lifecycle
 import androidx.lifecycle.*
 import dispatch.android.lifecycle.LifecycleScopeFactory.reset
 import dispatch.core.*
+import kotlinx.coroutines.*
+import kotlin.coroutines.*
 
 /**
  * Factory holder for [LifecycleCoroutineScope]'s.
  *
- * By default, `create` returns a [MainImmediateCoroutineScope].
+ * By default, `create` returns a [MainImmediateContext].
  *
  * This factory can be overridden for testing or to include a custom [CoroutineContext][kotlin.coroutines.CoroutineContext]
- * in production code.  This may be done in [Application.onCreate][android.app.Application.onCreate]
+ * in production code.  This may be done in [Application.onCreate][android.app.Application.onCreate],
+ * or else as early as possible in the Application's existence.
+ *
+ * A custom factory will persist for the application's full lifecycle unless overwritten or [reset].
  *
  * [reset] may be used to reset the factory to default at any time.
+ *
+ * @see MainImmediateContext
+ * @see LifecycleCoroutineScope
+ * @see LifecycleCoroutineScopeFactory
  * @sample samples.LifecycleScopeFactorySample.setLifecycleScopeFactoryProductionSample
  * @sample samples.LifecycleScopeFactorySample.setLifecycleScopeFactoryEspressoSample
  */
-public object LifecycleScopeFactory {
+object LifecycleScopeFactory {
+
+  private val defaultFactory: LifecycleCoroutineScopeFactory
+    get() = LifecycleCoroutineScopeFactory { MainImmediateContext() }
 
-  private var _factory: () -> MainImmediateCoroutineScope = { MainImmediateCoroutineScope() }
+  private var factoryInstance = defaultFactory
+
+  internal fun create(lifecycle: Lifecycle): LifecycleCoroutineScope =
+    factoryInstance.create(lifecycle)
+
+  /**
+   * Immediately resets the factory function to its default.
+   *
+   * @sample samples.LifecycleScopeFactorySample.LifecycleScopeFactoryResetSample
+   */
+  @Suppress("UNUSED")
+  public fun reset() {
+    factoryInstance = defaultFactory
+  }
 
   /**
    * Override the default [MainImmediateCoroutineScope] factory, for testing or to include a custom [CoroutineContext][kotlin.coroutines.CoroutineContext]
    * in production code.  This may be done in [Application.onCreate][android.app.Application.onCreate]
    *
-   * @param factory sets a custom [MainImmediateCoroutineScope] factory to be used for all new instance creations until reset.
+   * @param factory sets a custom [CoroutineContext] factory to be used for all new instance creations until reset.
+   * Its [Elements][CoroutineContext.Element] will be re-used, except:
+   * 1. If a [DispatcherProvider] element isn't present, a [DefaultDispatcherProvider] will be added.
+   * 2. If a [Job] element isn't present, a [SupervisorJob] will be added.
+   * 3. If the [ContinuationInterceptor][kotlin.coroutines.ContinuationInterceptor] does not match
+   * the one referenced by the [possibly new] [DispatcherProvider.mainImmediate] property, it will be updated to match.
    *
    * @sample samples.LifecycleScopeFactorySample.setLifecycleScopeFactoryProductionSample
    * @sample samples.LifecycleScopeFactorySample.setLifecycleScopeFactoryEspressoSample
    */
-  public fun set(factory: () -> MainImmediateCoroutineScope) {
-    _factory = factory
+  @Suppress("UNUSED")
+  public fun set(factory: LifecycleCoroutineScopeFactory) {
+    factoryInstance = factory
   }
 
-  internal fun create(lifecycle: Lifecycle) = LifecycleCoroutineScope(lifecycle, _factory.invoke())
-
   /**
-   * Immediately resets the factory function to its default.
+   * Override the default [MainImmediateCoroutineScope] factory, for testing or to include a custom [CoroutineContext][kotlin.coroutines.CoroutineContext]
+   * in production code.  This may be done in [Application.onCreate][android.app.Application.onCreate]
    *
-   * @sample samples.LifecycleScopeFactorySample.lifecycleScopeFactoryResetSample
+   * @param factory sets a custom [CoroutineContext] factory to be used for all new instance creations until reset.
+   * Its [Elements][CoroutineContext.Element] will be re-used, except:
+   * 1. If a [DispatcherProvider] element isn't present, a [DefaultDispatcherProvider] will be added.
+   * 2. If a [Job] element isn't present, a [SupervisorJob] will be added.
+   * 3. If the [ContinuationInterceptor][kotlin.coroutines.ContinuationInterceptor] does not match
+   * the one referenced by the [possibly new] [DispatcherProvider.mainImmediate] property, it will be updated to match.
+   *
+   * @sample samples.LifecycleScopeFactorySample.setLifecycleScopeFactoryProductionSample
+   * @sample samples.LifecycleScopeFactorySample.setLifecycleScopeFactoryEspressoSample
    */
-  public fun reset() {
-    _factory = { MainImmediateCoroutineScope() }
+  @Suppress("UNUSED")
+  public fun set(factory: () -> CoroutineContext) {
+    factoryInstance = LifecycleCoroutineScopeFactory(factory)
   }
 
 }

dispatch-android-lifecycle-extensions/src/main/java/dispatch/android/lifecycle/lifecycleScope.kt

@@ -31,7 +31,7 @@ import kotlinx.coroutines.*
  * The `viewModelScope` is automatically cancelled when the [LifecycleOwner]'s
  * [lifecycle][LifecycleOwner.getLifecycle]'s [Lifecycle.State] drops to [Lifecycle.State.DESTROYED].
  *
- * @sample samples.LifecycleCoroutineScopeSample.lifecycleCoroutineScopeSample
+ * @sample samples.LifecycleScopeSample.lifecycleScopeSample
  */
 val LifecycleOwner.lifecycleScope: LifecycleCoroutineScope
   get() = LifecycleCoroutineScopeStore.get(this.lifecycle)

dispatch-android-lifecycle-extensions/src/test/java/dispatch/android/lifecycle/LifecycleScopeExtensionTest.kt

@@ -40,17 +40,12 @@ internal class LifecycleScopeExtensionTest : HermitJUnit5() {
 
     val dispatcher = TestCoroutineDispatcher()
 
-    LifecycleScopeFactory.set {
-      TestProvidedCoroutineScope(
-        dispatcher,
-        TestDispatcherProvider(dispatcher),
-        Job()
-      )
-    }
+    LifecycleScopeFactory.set { dispatcher + TestDispatcherProvider(dispatcher) + Job() }
   }
 
   @AfterEach
   fun afterEach() {
+    LifecycleScopeFactory.reset()
     storeMap.clear()
   }
 

dispatch-android-lifecycle-extensions/src/test/java/dispatch/android/lifecycle/LifecycleScopeFactoryTest.kt

@@ -45,6 +45,7 @@ internal class LifecycleScopeFactoryTest : HermitJUnit5() {
 
   @BeforeAll
   fun beforeAll() {
+    LifecycleScopeFactory.reset()
     Dispatchers.setMain(mainDispatcher)
   }
 
@@ -59,7 +60,7 @@ internal class LifecycleScopeFactoryTest : HermitJUnit5() {
   }
 
   @Test
-  fun `default factory should be a default MainImmediateCoroutineScope`() = runBlockingTest {
+  fun `default factory should be a default MainImmediateContext`() = runBlockingTest {
 
     val scope = LifecycleScopeFactory.create(lifecycleOwner.lifecycle)
 
@@ -68,14 +69,12 @@ internal class LifecycleScopeFactoryTest : HermitJUnit5() {
     scope.coroutineContext[Job]!!.shouldBeSupervisorJob()
 
     scope.coroutineContext[ContinuationInterceptor] shouldBe Dispatchers.Main
-
-    scope.shouldBeInstanceOf<MainImmediateCoroutineScope>()
   }
 
   @Test
   fun `a custom factory should be used after being set`() = runBlockingTest {
 
-    LifecycleScopeFactory.set { MainImmediateCoroutineScope(originContext) }
+    LifecycleScopeFactory.set { originContext }
 
     val scope = LifecycleScopeFactory.create(lifecycleOwner.lifecycle)
 
@@ -85,7 +84,7 @@ internal class LifecycleScopeFactoryTest : HermitJUnit5() {
   @Test
   fun `reset after setting a custom factory should return to the default`() = runBlockingTest {
 
-    LifecycleScopeFactory.set { MainImmediateCoroutineScope(originContext) }
+    LifecycleScopeFactory.set { originContext }
 
     val custom = LifecycleScopeFactory.create(lifecycleOwner.lifecycle)