diff --git a/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/Zenoh.kt b/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/Zenoh.kt index b41175c0d..d3cfcf518 100644 --- a/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/Zenoh.kt +++ b/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/Zenoh.kt @@ -21,28 +21,45 @@ import io.zenoh.jni.JNIScout import io.zenoh.scouting.Hello import io.zenoh.scouting.Scout import io.zenoh.scouting.WhatAmI +import io.zenoh.scouting.WhatAmI.* import kotlinx.coroutines.channels.Channel -/** - * Static singleton class to load the Zenoh native library once and only once, as well as the logger in function of the - * log level configuration. - */ -internal expect object ZenohLoad - object Zenoh { + /** + * Scout for routers and/or peers. + * + * Scout spawns a task that periodically sends scout messages and waits for Hello replies. + * Drop the returned Scout to stop the scouting task or explicitly call [Scout.stop] or [Scout.close]. + * + * @param callback [Callback] to be run when receiving a [Hello] message. + * @param whatAmI [WhatAmI] configuration: it indicates the role of the zenoh node sending the HELLO message. + * @param config Optional [Config] for the scout. + * @return A [Scout] object. + */ fun scout( callback: Callback, - whatAmI: Set = setOf(WhatAmI.Peer), + whatAmI: Set = setOf(Peer, Router), config: Config? = null ): Scout { ZenohLoad return JNIScout.scout(whatAmI = whatAmI, callback = callback, receiver = Unit, config = config) } + /** + * Scout for routers and/or peers. + * + * Scout spawns a task that periodically sends scout messages and waits for Hello replies. + * Drop the returned Scout to stop the scouting task or explicitly call [Scout.stop] or [Scout.close]. + * + * @param handler [Handler] to handle incoming [Hello] messages. + * @param whatAmI [WhatAmI] configuration: it indicates the role of the zenoh node sending the HELLO message. + * @param config Optional [Config] for the scout. + * @return A [Scout] object. + */ fun scout( handler: Handler, - whatAmI: Set = setOf(WhatAmI.Peer), + whatAmI: Set = setOf(Peer, Router), config: Config? = null ): Scout { ZenohLoad @@ -54,9 +71,20 @@ object Zenoh { ) } + /** + * Scout for routers and/or peers. + * + * Scout spawns a task that periodically sends scout messages and waits for Hello replies. + * Drop the returned Scout to stop the scouting task or explicitly call [Scout.stop] or [Scout.close]. + * + * @param channel [Channel] upon which the incoming [Hello] messages will be piped. + * @param whatAmI [WhatAmI] configuration: it indicates the role of the zenoh node sending the HELLO message. + * @param config Optional [Config] for the scout. + * @return A [Scout] object. + */ fun scout( channel: Channel, - whatAmI: Set = setOf(WhatAmI.Peer), + whatAmI: Set = setOf(Peer, Router), config: Config? = null ): Scout> { ZenohLoad @@ -68,4 +96,10 @@ object Zenoh { config = config ) } -} \ No newline at end of file +} + +/** + * Static singleton class to load the Zenoh native library once and only once, as well as the logger in function of the + * log level configuration. + */ +internal expect object ZenohLoad diff --git a/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/Hello.kt b/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/Hello.kt index 51d3b35bb..c3cbe20b8 100644 --- a/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/Hello.kt +++ b/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/Hello.kt @@ -1,6 +1,28 @@ +// +// Copyright (c) 2023 ZettaScale Technology +// +// This program and the accompanying materials are made available under the +// terms of the Eclipse Public License 2.0 which is available at +// http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 +// which is available at https://www.apache.org/licenses/LICENSE-2.0. +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// +// Contributors: +// ZettaScale Zenoh Team, +// + package io.zenoh.scouting import io.zenoh.ZenohType import io.zenoh.protocol.ZenohID -data class Hello(val whatAmI: WhatAmI, val zid: ZenohID, val locators: List): ZenohType \ No newline at end of file +/** + * Hello message received while scouting. + * + * @property whatAmI [WhatAmI] configuration: it indicates the role of the zenoh node sending the HELLO message. + * @property zid [ZenohID] of the node sending the hello message. + * @property locators The locators of this hello message. + * @see Scout + */ +data class Hello(val whatAmI: WhatAmI, val zid: ZenohID, val locators: List): ZenohType diff --git a/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/Scout.kt b/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/Scout.kt index 15e3b26ad..e7f311790 100644 --- a/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/Scout.kt +++ b/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/Scout.kt @@ -1,19 +1,51 @@ +// +// Copyright (c) 2023 ZettaScale Technology +// +// This program and the accompanying materials are made available under the +// terms of the Eclipse Public License 2.0 which is available at +// http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 +// which is available at https://www.apache.org/licenses/LICENSE-2.0. +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// +// Contributors: +// ZettaScale Zenoh Team, +// + package io.zenoh.scouting import io.zenoh.jni.JNIScout +/** + * Scout for routers and/or peers. + * + * Scout spawns a task that periodically sends scout messages and waits for Hello replies. + * Drop the returned Scout to stop the scouting task. + * + * @param R The receiver type. + * @param receiver Receiver to handle incoming hello messages. + */ class Scout internal constructor( val receiver: R, - private val jniScout: JNIScout? + private var jniScout: JNIScout? ) : AutoCloseable { + /** + * Stops the scouting. + */ fun stop() { jniScout?.close() + jniScout = null } + /** + * Equivalent to [stop]. + */ override fun close() { stop() } -} - + protected fun finalize() { + stop() + } +} diff --git a/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/WhatAmI.kt b/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/WhatAmI.kt index 5919c5a8b..6296ee7bb 100644 --- a/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/WhatAmI.kt +++ b/zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/WhatAmI.kt @@ -1,5 +1,24 @@ +// +// Copyright (c) 2023 ZettaScale Technology +// +// This program and the accompanying materials are made available under the +// terms of the Eclipse Public License 2.0 which is available at +// http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 +// which is available at https://www.apache.org/licenses/LICENSE-2.0. +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// +// Contributors: +// ZettaScale Zenoh Team, +// + package io.zenoh.scouting +/** + * WhatAmI + * + * The role of the node sending the `hello` message. + */ enum class WhatAmI(internal val value: Int) { Router(1), Peer(2), @@ -8,4 +27,4 @@ enum class WhatAmI(internal val value: Int) { companion object { internal fun fromInt(value: Int) = entries.first { value == it.value } } -} \ No newline at end of file +}