github-repos/mirai
1
0
Fork 0
mirror of https://github.com/mamoe/mirai.git synced 2025-01-19 13:54:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Improve implementation docs

Browse Source
This commit is contained in:
Him188 2021-06-05 13:46:03 +08:00
parent 083a3a1e00
commit 8ae2e04f02
5 changed files with 19 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
mirai-core/src/commonMain/kotlin/network/handler/NetworkHandler.kt
View File

@ -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)

2
mirai-core/src/commonMain/kotlin/network/handler/NetworkHandlerSupport.kt
View File

@ -111,7 +111,7 @@ internal abstract class NetworkHandlerSupport(
}
///////////////////////////////////////////////////////////////////////////
// await impl
// packets synchronization impl
///////////////////////////////////////////////////////////////////////////
protected class PacketListener(

2
mirai-core/src/commonMain/kotlin/network/handler/selector/AbstractKeepAliveNetworkHandlerSelector.kt
View File

@ -67,7 +67,7 @@ internal abstract class AbstractKeepAliveNetworkHandlerSelector<H : NetworkHandl
NetworkHandler.State.CONNECTING,
NetworkHandler.State.INITIALIZED -> {
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 -> {

7
mirai-core/src/commonMain/kotlin/network/handler/selector/NetworkHandlerSelector.kt
View File

@ -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<H : NetworkHandler> {
/**

1
mirai-core/src/commonMain/kotlin/network/handler/selector/SelectorNetworkHandler.kt
View File

@ -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].
*