commonMain.com.squareup.wire.MessageSource.kt Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of wire-runtime-js Show documentation

gRPC and protocol buffers for Android, Kotlin, and Java.

There is a newer version: 5.0.0

/*
 * Copyright 2019 Square Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.squareup.wire

import com.squareup.wire.internal.Throws
import okio.IOException

/**
 * A readable stream of messages.
 *
 * Typical implementations will receive messages recently transmitted from a peer, such as for
 * server-to-client or client-to-server networking. But this implementation is not limited to such
 * networking use cases and implementations may load messages from local storage or generate
 * messages on demand.
 *
 * Calls to [read] will block until a message becomes available. There is no mechanism to limit how
 * long a specific [read] will wait, though implementations may be configured to fail if they
 * consider a source to be unhealthy.
 *
 * Readers should take care to keep up with the stream of messages. A reader that takes an excessive
 * amount of time to process a message may cause their writer to back up and suffer queueing.
 *
 * Instances of this interface are not safe for concurrent use.
 */
expect interface MessageSource {
  /**
   * Read the next length-prefixed message on the stream and return it. Returns null if there are
   * no further messages on this stream.
   *
   * @throws IOException if the next message cannot be read, or if the stream was abnormally
   *     terminated by its producer.
   */
  @Throws(IOException::class)
  fun read(): T?

  @Throws(IOException::class)
  fun close()
}