From d1c9284d88f7ebfd0aef8f68c3963bb769137c48 Mon Sep 17 00:00:00 2001 From: Filipp Zhinkin Date: Mon, 23 Sep 2024 13:10:18 -0400 Subject: [PATCH 1/2] Improve documentation Explicitly documents thread-safety guarantees, PeelSource behavior and FileSystem support for JS-target. Closes #392, #393, #394 --- core/Module.md | 4 ++++ core/common/src/Buffer.kt | 6 ++++++ core/common/src/RawSink.kt | 5 +++++ core/common/src/RawSource.kt | 5 +++++ core/common/src/Sink.kt | 7 ++++++- core/common/src/Source.kt | 13 ++++++++++++- core/common/src/files/FileSystem.kt | 10 +++++++++- 7 files changed, 47 insertions(+), 3 deletions(-) diff --git a/core/Module.md b/core/Module.md index 840b92af8..0fef6a6ca 100644 --- a/core/Module.md +++ b/core/Module.md @@ -83,6 +83,10 @@ Core IO primitives. Basic API for working with files. +#### Thread-safety guarantees + +Until stated otherwise, types and functions provided by the library are not thread safe. + #### Known issues - [#312](https://github.com/Kotlin/kotlinx-io/issues/312) For `wasmWasi` target, directory listing ([kotlinx.io.files.FileSystem.list]) does not work with NodeJS runtime on Windows, diff --git a/core/common/src/Buffer.kt b/core/common/src/Buffer.kt index d2c5dc967..92334a27a 100644 --- a/core/common/src/Buffer.kt +++ b/core/common/src/Buffer.kt @@ -41,6 +41,12 @@ import kotlin.jvm.JvmSynthetic * [Buffer] implements both [Source] and [Sink] and could be used as a source or a sink, * but unlike regular sinks and sources its [close], [flush], [emit], [hintEmit] * does not affect buffer's state and [exhausted] only indicates that a buffer is empty. + * + * ### Thread-safety guarantees + * + * [Buffer] does not provide any thread-safety guarantees. + * If a [Buffer] needs to be accessed from multiple threads, an additional synchronization is required. + * Failure to do so will result in possible data corruption, loss, and runtime errors. */ public class Buffer : Source, Sink { @PublishedApi diff --git a/core/common/src/RawSink.kt b/core/common/src/RawSink.kt index 473d0cf05..5c7930df7 100644 --- a/core/common/src/RawSink.kt +++ b/core/common/src/RawSink.kt @@ -32,6 +32,11 @@ package kotlinx.io * * Implementors should abstain from throwing exceptions other than those that are documented for RawSink methods. * + * ### Thread-safety guarantees + * + * [RawSink] implementations are not required to be thread safe. + * However, if an implementation provides some thread safety guarantees, it's recommended to explicitly document them. + * * @sample kotlinx.io.samples.Crc32Sample.crc32 */ public expect interface RawSink : AutoCloseable { diff --git a/core/common/src/RawSource.kt b/core/common/src/RawSource.kt index 1d16c58ca..19066f342 100644 --- a/core/common/src/RawSource.kt +++ b/core/common/src/RawSource.kt @@ -32,6 +32,11 @@ package kotlinx.io * * Implementors should abstain from throwing exceptions other than those that are documented for RawSource methods. * + * ### Thread-safety guarantees + * + * [RawSource] implementations are not required to be thread safe. + * However, if an implementation provides some thread safety guarantees, it's recommended to explicitly document them. + * * @sample kotlinx.io.samples.RC4SourceSample.rc4 */ public interface RawSource : AutoCloseable { diff --git a/core/common/src/Sink.kt b/core/common/src/Sink.kt index e2914fd5f..e848fc7c2 100644 --- a/core/common/src/Sink.kt +++ b/core/common/src/Sink.kt @@ -1,5 +1,5 @@ /* - * Copyright 2017-2023 JetBrains s.r.o. and respective authors and developers. + * Copyright 2017-2024 JetBrains s.r.o. and respective authors and developers. * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENCE file. */ @@ -50,6 +50,11 @@ package kotlinx.io * Methods fully consuming its argument are named `transferFrom`, like [transferFrom]. * * It is recommended to follow the same naming convention for Sink extensions. + * + * ### Thread-safety guarantees + * + * Until stated otherwise, [Sink] implementations are not thread safe. + * If a [Sink] needs to be accessed from multiple threads, an additional synchronization is required. */ public sealed interface Sink : RawSink { /** diff --git a/core/common/src/Source.kt b/core/common/src/Source.kt index e6a5b349b..90dd48eaf 100644 --- a/core/common/src/Source.kt +++ b/core/common/src/Source.kt @@ -1,5 +1,5 @@ /* - * Copyright 2017-2023 JetBrains s.r.o. and respective authors and developers. + * Copyright 2017-2024 JetBrains s.r.o. and respective authors and developers. * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENCE file. */ @@ -58,6 +58,11 @@ package kotlinx.io * Methods moving all data from a source to some other sink are named `transferTo`, like [transferTo]. * * It is recommended to follow the same naming convention for Source extensions. + * + * ### Thread-safety guarantees + * + * Until stated otherwise, [Source] implementations are not thread safe. + * If a [Source] needs to be accessed from multiple threads, an additional synchronization is required. */ public sealed interface Source : RawSource { /** @@ -229,6 +234,12 @@ public sealed interface Source : RawSource { * * Peek could be used to lookahead and read the same data multiple times. * + * If peek source needs to access more data that this [Source] has in its buffer, + * more data will be requested from the underlying source and on success, + * it'll be added to the buffer of this [Source]. + * If the underlying source was exhausted or some error occurred on attempt to fill the buffer, + * a corresponding exception will be thrown. + * * @throws IllegalStateException when the source is closed. * * @sample kotlinx.io.samples.KotlinxIoCoreCommonSamples.peekSample diff --git a/core/common/src/files/FileSystem.kt b/core/common/src/files/FileSystem.kt index de000d447..46c40af65 100644 --- a/core/common/src/files/FileSystem.kt +++ b/core/common/src/files/FileSystem.kt @@ -1,5 +1,5 @@ /* - * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors. + * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors. * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE.txt file. */ @@ -21,6 +21,11 @@ import kotlinx.io.RawSource * access to some network resources and allow working with them as with regular files, for example. * * **This API is unstable and subject to change.** + * + * ### Thread-safety guarantees + * + * Until stated otherwise, [FileSystem] implementation are not thread safe. + * If a [FileSystem] needs to be accessed from multiple threads, an additional synchronization is required. */ public sealed interface FileSystem { /** @@ -170,6 +175,9 @@ internal abstract class SystemFileSystemImpl : FileSystem /** * An instance of [FileSystem] representing a default system-wide filesystem. + * + * *For `js` target, `SystemFileSystem` is only supported in `nodeJs` environment. Attempts to use it in `browser` + * environment will result in runtime exception being thrown.* */ public expect val SystemFileSystem: FileSystem From 78e4422d4cf9aeaa71a96b021eda09c0070ec27f Mon Sep 17 00:00:00 2001 From: Filipp Zhinkin Date: Mon, 23 Sep 2024 14:50:28 -0400 Subject: [PATCH 2/2] s/it's/it is/g --- core/common/src/RawSink.kt | 2 +- core/common/src/RawSource.kt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/core/common/src/RawSink.kt b/core/common/src/RawSink.kt index 5c7930df7..a7c9d74c3 100644 --- a/core/common/src/RawSink.kt +++ b/core/common/src/RawSink.kt @@ -35,7 +35,7 @@ package kotlinx.io * ### Thread-safety guarantees * * [RawSink] implementations are not required to be thread safe. - * However, if an implementation provides some thread safety guarantees, it's recommended to explicitly document them. + * However, if an implementation provides some thread safety guarantees, it is recommended to explicitly document them. * * @sample kotlinx.io.samples.Crc32Sample.crc32 */ diff --git a/core/common/src/RawSource.kt b/core/common/src/RawSource.kt index 19066f342..3b7d7e687 100644 --- a/core/common/src/RawSource.kt +++ b/core/common/src/RawSource.kt @@ -35,7 +35,7 @@ package kotlinx.io * ### Thread-safety guarantees * * [RawSource] implementations are not required to be thread safe. - * However, if an implementation provides some thread safety guarantees, it's recommended to explicitly document them. + * However, if an implementation provides some thread safety guarantees, it is recommended to explicitly document them. * * @sample kotlinx.io.samples.RC4SourceSample.rc4 */