DataConnectLogging.kt major refactor'

Author: dconeybe

firebase-dataconnect/gradle.properties

@@ -1,2 +1,2 @@
-version=16.0.0-beta04
+version=16.0.0-beta99
 latestReleasedVersion=16.0.0-beta03

firebase-dataconnect/src/main/kotlin/com/google/firebase/dataconnect/DataConnectLogging.kt

@@ -38,7 +38,7 @@ import kotlinx.coroutines.flow.Flow
  * The [DataConnectLogging] interface is _not_ stable for inheritance in third-party libraries, as
  * new methods might be added to this interface or contracts of the existing methods can be changed.
  */
-public interface DataConnectLogging {
+public interface DataConnectLogging<out StateT : DataConnectLogging.State> {
 
   /**
    * The log level use by all [FirebaseDataConnect] instances.
@@ -49,63 +49,76 @@ public interface DataConnectLogging {
    */
   public var level: LogLevel
 
-  /** A [Flow] that can be used to observe the changes to [level]. */
-  public val flow: Flow<LogLevel>
+  /** A [Flow] that can be used to observe changes to [state]. */
+  public val flow: Flow<StateT>
 
   /**
-   * Sets the log level to the given level, as if by setting [level], and returns an object that,
-   * when closed, will restore the log level to the value it was at the time that this method was
-   * invoked.
+   * The state of the logging facilities.
    *
-   * This method can be particularly useful to enable debug logging only for a small section of
-   * code, without having to manually keep track of the original state. Unit tests and small chunks
-   * of code that require debugging are the intended use cases for this function.
+   * A caller may wish to save the value of this property into a local variable, make some changes
+   * to the public properties of [DataConnectLogging] (for example, change [level]), run some code,
+   * then restore the original state by calling [DataConnectLogging.State.restore].
    *
    * For an example in Firebase Data Connect's own Android test suite, see https://goo.gle/3ZuRug5.
-   *
-   * Note that when a log level is "popped" it does not interact with any other pushed log levels.
-   * In particular, if there are nested calls to [push] then they are expected to be popped in
-   * reverse order; otherwise, the "original" log level may not be properly restored.
    */
-  public fun push(level: LogLevel): LogLevelStackFrame
+  public val state: StateT
 
   /**
-   * A "stack frame" that saves the state of the logging facilities in response to a call to [push].
+   * A snapshot of the state of the logging facilities, that can be later restored.
    *
    * ### Safe for Concurrent Use
    *
-   * All methods and properties of [LogLevelStackFrame] are thread-safe and may be safely called
-   * and/or accessed concurrently from multiple threads and/or coroutines.
+   * All methods and properties of [State] are thread-safe and may be safely called and/or accessed
+   * concurrently from multiple threads and/or coroutines.
    *
    * ### Not Stable for Inheritance
    *
-   * The [LogLevelStackFrame] interface is _not_ stable for inheritance in third-party libraries, as
-   * new methods might be added to this interface or contracts of the existing methods can be
-   * changed.
+   * The [State] interface is _not_ stable for inheritance in third-party libraries, as new methods
+   * might be added to this interface or contracts of the existing methods can be changed.
+   *
+   * @see state
    */
-  public interface LogLevelStackFrame : AutoCloseable {
+  public interface State {
 
-    /** The log level that was in place when this frame was pushed. */
-    public val originalLevel: LogLevel
+    /** The log level. */
+    public val level: LogLevel
 
-    /** The log level that was set when this frame was pushed. */
-    public val newLevel: LogLevel
+    /** Restores the state from this object into the [DataConnectLogging] that created it. */
+    public fun restore()
 
     /**
-     * Pops this frame off of the log level stack, restoring the log level to the state it was in at
-     * the time that this frame was pushed onto the stack.
+     * Compares this object with another object for equality.
      *
-     * This method may be safely called multiple times. Subsequent invocations will do nothing and
-     * return as if successful. Subsequent invocations will _block_ until the state is restored by
-     * the thread that is actually doing the restoring.
+     * @param other The object to compare to this for equality.
+     * @return true if, and only if, the other object is an instance of the same implementation of
+     * [State] whose public properties compare equal using the `==` operator to the corresponding
+     * properties of this object.
      */
-    override fun close()
+    override fun equals(other: Any?): Boolean
 
     /**
-     * Does the exact same thing as [close], except that it _suspends_ rather than _blocks_ if
-     * another thread is in the process of restoring the original log level.
+     * Calculates and returns the hash code for this object.
+     *
+     * The hash code is _not_ guaranteed to be stable across application restarts.
+     *
+     * @return the hash code for this object, that incorporates the values of this object's public
+     * properties.
      */
-    public suspend fun suspendingClose()
+    override fun hashCode(): Int
+
+    /**
+     * Returns a string representation of this object, useful for debugging.
+     *
+     * The string representation is _not_ guaranteed to be stable and may change without notice at
+     * any time. Therefore, the only recommended usage of the returned string is debugging and/or
+     * logging. Namely, parsing the returned string or storing the returned string in non-volatile
+     * storage should generally be avoided in order to be robust in case that the string
+     * representation changes.
+     *
+     * @return a string representation of this object, which includes the class name and the values
+     * of all public properties.
+     */
+    override fun toString(): String
   }
 }
 
@@ -126,5 +139,12 @@ public interface DataConnectLogging {
  * inline.
  * @return whatever the given block returns.
  */
-public inline fun <T> DataConnectLogging.withLevel(level: LogLevel, block: () -> T): T =
-  push(level).use { block() }
+public inline fun <T> DataConnectLogging<*>.withLevel(level: LogLevel, block: () -> T): T {
+  val savedState = state
+  this.level = level
+  return try {
+    block()
+  } finally {
+    savedState.restore()
+  }
+}

firebase-dataconnect/src/main/kotlin/com/google/firebase/dataconnect/FirebaseDataConnect.kt

@@ -396,5 +396,5 @@ public var FirebaseDataConnect.Companion.logLevel: LogLevel
   }
 
 /** The logcat logging facilities used by all [FirebaseDataConnect] instances. */
-public val FirebaseDataConnect.Companion.logging: DataConnectLogging
+public val FirebaseDataConnect.Companion.logging: DataConnectLogging<*>
   get() = DataConnectLoggingImpl

firebase-dataconnect/src/main/kotlin/com/google/firebase/dataconnect/core/DataConnectLoggingImpl.kt

@@ -19,52 +19,39 @@ package com.google.firebase.dataconnect.core
 import android.util.Log
 import com.google.firebase.dataconnect.BuildConfig
 import com.google.firebase.dataconnect.DataConnectLogging
-import com.google.firebase.dataconnect.DataConnectLogging.LogLevelStackFrame
 import com.google.firebase.dataconnect.LogLevel
 import com.google.firebase.dataconnect.core.LoggerGlobals.LOG_TAG
 import com.google.firebase.dataconnect.core.LoggerGlobals.Logger
 import com.google.firebase.util.nextAlphanumericString
 import kotlin.random.Random
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.asSharedFlow
-import kotlinx.coroutines.runBlocking
-import kotlinx.coroutines.sync.Mutex
-import kotlinx.coroutines.sync.withLock
 
-internal object DataConnectLoggingImpl : DataConnectLogging {
+internal object DataConnectLoggingImpl : DataConnectLogging<DataConnectLoggingImpl.StateImpl> {
 
-  private val _level = MutableStateFlow(LogLevel.WARN)
+  private val _state = MutableStateFlow(StateImpl(level = LogLevel.WARN))
 
-  override val flow = _level.asSharedFlow()
+  override val flow = _state.asSharedFlow()
 
-  override var level by _level::value
+  override val state
+    get() = _state.value
 
-  override fun push(level: LogLevel): LogLevelStackFrame {
-    while (true) {
-      val originalLevel = _level.value
-      if (_level.compareAndSet(originalLevel, level)) {
-        return LogLevelStackFrameImpl(originalLevel, level)
+  override var level: LogLevel
+    get() = _state.value.level
+    set(newLevel) {
+      while (true) {
+        val oldState = _state.value
+        val newState = oldState.copy(level = newLevel)
+        if (_state.compareAndSet(oldState, newState)) {
+          break
+        }
       }
     }
-  }
-
-  private data class LogLevelStackFrameImpl(
-    override val originalLevel: LogLevel,
-    override val newLevel: LogLevel,
-  ) : LogLevelStackFrame {
-
-    private val closedMutex = Mutex()
-    private var closed = false
 
-    override fun close() = runBlocking { suspendingClose() }
-
-    override suspend fun suspendingClose() =
-      closedMutex.withLock {
-        if (!closed) {
-          level = originalLevel
-          closed = true
-        }
-      }
+  data class StateImpl(override val level: LogLevel) : DataConnectLogging.State {
+    override fun restore() {
+      _state.value = this
+    }
   }
 }