From 8ae2e04f023bbcafd66cea99fb0ac48c54771794 Mon Sep 17 00:00:00 2001 From: Him188 Date: Sat, 5 Jun 2021 13:46:03 +0800 Subject: [PATCH] Improve implementation docs --- .../kotlin/network/handler/NetworkHandler.kt | 20 +++++++++---------- .../network/handler/NetworkHandlerSupport.kt | 2 +- ...AbstractKeepAliveNetworkHandlerSelector.kt | 2 +- .../selector/NetworkHandlerSelector.kt | 7 ++++++- .../selector/SelectorNetworkHandler.kt | 1 + 5 files changed, 19 insertions(+), 13 deletions(-) diff --git a/mirai-core/src/commonMain/kotlin/network/handler/NetworkHandler.kt b/mirai-core/src/commonMain/kotlin/network/handler/NetworkHandler.kt index 6ab8f6e71..7083020f0 100644 --- a/mirai-core/src/commonMain/kotlin/network/handler/NetworkHandler.kt +++ b/mirai-core/src/commonMain/kotlin/network/handler/NetworkHandler.kt @@ -57,14 +57,12 @@ internal interface NetworkHandler : CoroutineScope { * On [State.CONNECTING], [NetworkHandler] establishes a connection with the server while [SsoProcessor] takes responsibility in the single-sign-on process. * * Successful logon turns state to [State.LOADING], an **open state**, which does nothing by default. Jobs can be *attached* by [StateObserver]s. - * For example, attaching a [BotInitProcessor] to handle session-relevant jobs to the [Bot]. + * For example, attaching a [BotInitProcessor] to handle account-relevant jobs to the [Bot]. * - * Failure during [State.CONNECTING] and [State.LOADING] switches state to [State.CLOSED], on which [NetworkHandler] is considered permanently dead. - * - * The state after finish of [State.LOADING] is [State.OK]. This state lasts for the majority of time. - * - * When connection is lost (e.g. due to Internet unavailability), it does NOT return to [State.CONNECTING] but to [State.CLOSED]. No attempts is allowed. + * Failure during [State.CONNECTING] and [State.LOADING] switches state to [State.CLOSED], on which [NetworkHandler] is considered **permanently dead**. + * The state after finishing of [State.LOADING] is [State.OK]. This state lasts for the majority of time. * + * When connection is lost (e.g. due to Internet unavailability), it does NOT return to [State.CONNECTING] but to [State.CLOSED]. No reconnection is allowed. * Retrial may only be performed in [SelectorNetworkHandler]. * * @see state @@ -124,9 +122,10 @@ internal interface NetworkHandler : CoroutineScope { /** - * Sends [packet] and expects to receive a response from the server. + * Sends [packet], suspends and expects to receive a response from the server. * - * Coroutine suspension may happen if connection if not yet available however, [IllegalStateException] is thrown if [NetworkHandler] is already in [State.CLOSED] + * Coroutine suspension may happen if connection is not yet available however, + * [IllegalStateException] is thrown if [NetworkHandler] is already in [State.CLOSED] since closure is final. * * @param attempts ranges `1..INFINITY` */ @@ -135,8 +134,9 @@ internal interface NetworkHandler : CoroutineScope { /** * Sends [packet] and does not expect any response. * - * Response is still being processed but not passed as a return value of this function, so it does not suspends this function. - * However, coroutine is still suspended if connection if not yet available, and [IllegalStateException] is thrown if [NetworkHandler] is already in [State.CLOSED] + * Response is still being processed but not passed as a return value of this function, so it does not suspends this function (due to awaiting for the response). + * However, coroutine is still suspended if connection is not yet available, + * and [IllegalStateException] is thrown if [NetworkHandler] is already in [State.CLOSED] since closure is final. */ suspend fun sendWithoutExpect(packet: OutgoingPacket) diff --git a/mirai-core/src/commonMain/kotlin/network/handler/NetworkHandlerSupport.kt b/mirai-core/src/commonMain/kotlin/network/handler/NetworkHandlerSupport.kt index 74e50d6a0..580669376 100644 --- a/mirai-core/src/commonMain/kotlin/network/handler/NetworkHandlerSupport.kt +++ b/mirai-core/src/commonMain/kotlin/network/handler/NetworkHandlerSupport.kt @@ -111,7 +111,7 @@ internal abstract class NetworkHandlerSupport( } /////////////////////////////////////////////////////////////////////////// - // await impl + // packets synchronization impl /////////////////////////////////////////////////////////////////////////// protected class PacketListener( diff --git a/mirai-core/src/commonMain/kotlin/network/handler/selector/AbstractKeepAliveNetworkHandlerSelector.kt b/mirai-core/src/commonMain/kotlin/network/handler/selector/AbstractKeepAliveNetworkHandlerSelector.kt index 16832ae0a..fc5082c8b 100644 --- a/mirai-core/src/commonMain/kotlin/network/handler/selector/AbstractKeepAliveNetworkHandlerSelector.kt +++ b/mirai-core/src/commonMain/kotlin/network/handler/selector/AbstractKeepAliveNetworkHandlerSelector.kt @@ -67,7 +67,7 @@ internal abstract class AbstractKeepAliveNetworkHandlerSelector { current.resumeConnection() // once finished, it should has been LOADING or OK - check(current.state != thisState) { "State is still $thisState after successful resumeConnection." } + check(current.state != thisState) { "Internal error: State is still $thisState after successful resumeConnection." } // this should not happen. return awaitResumeInstanceImpl(attempted) // does not count for an attempt. } NetworkHandler.State.LOADING -> { diff --git a/mirai-core/src/commonMain/kotlin/network/handler/selector/NetworkHandlerSelector.kt b/mirai-core/src/commonMain/kotlin/network/handler/selector/NetworkHandlerSelector.kt index e5a118350..e1e2cef93 100644 --- a/mirai-core/src/commonMain/kotlin/network/handler/selector/NetworkHandlerSelector.kt +++ b/mirai-core/src/commonMain/kotlin/network/handler/selector/NetworkHandlerSelector.kt @@ -10,9 +10,14 @@ package net.mamoe.mirai.internal.network.handler.selector import net.mamoe.mirai.internal.network.handler.NetworkHandler +import net.mamoe.mirai.internal.network.handler.NetworkHandlerFactory /** - * A lazy stateful selector of [NetworkHandler]. This is used as a director([selector][SelectorNetworkHandler.selector]) to [SelectorNetworkHandler]. + * A director([selector][SelectorNetworkHandler.selector]) of [NetworkHandler]. + * + * It can produce [H] instances (maybe by calling [NetworkHandlerFactory]), to be used by [SelectorNetworkHandler] + * + * @see SelectorNetworkHandler */ internal interface NetworkHandlerSelector { /** diff --git a/mirai-core/src/commonMain/kotlin/network/handler/selector/SelectorNetworkHandler.kt b/mirai-core/src/commonMain/kotlin/network/handler/selector/SelectorNetworkHandler.kt index d660eaab8..9cb05bd02 100644 --- a/mirai-core/src/commonMain/kotlin/network/handler/selector/SelectorNetworkHandler.kt +++ b/mirai-core/src/commonMain/kotlin/network/handler/selector/SelectorNetworkHandler.kt @@ -19,6 +19,7 @@ import kotlin.coroutines.CoroutineContext /** * A proxy to [NetworkHandler] that delegates calls to instance returned by [NetworkHandlerSelector.awaitResumeInstance]. + * Selection logic is implemented in [NetworkHandlerSelector]. * * This is useful to implement a delegation of [NetworkHandler]. The functionality of *selection* is provided by the strategy [selector][NetworkHandlerSelector]. *