io.servicetalk.concurrent.internal.SignalOffloader Maven / Gradle / Ivy
/*
* Copyright © 2018 Apple Inc. and the ServiceTalk project authors
*
* 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 io.servicetalk.concurrent.internal;
import io.servicetalk.concurrent.Cancellable;
import io.servicetalk.concurrent.CompletableSource;
import io.servicetalk.concurrent.PublisherSource.Subscriber;
import io.servicetalk.concurrent.PublisherSource.Subscription;
import io.servicetalk.concurrent.SingleSource;
import java.util.function.Consumer;
/**
* A contract to offload signals to and
* from any asynchronous source.
*
* Caution
* A {@link SignalOffloader} instance MUST only be used for a single asynchronous execution chain at
* any given time. Reusing it across different execution chains concurrently may result in deadlock.
* Concurrent invocation of any {@link SignalOffloader} methods may result in deadlock.
*/
public interface SignalOffloader {
/**
* Decorates the passed {@link Subscriber} such that all method calls to it will be offloaded.
*
*
Caution
* This method MUST not be called concurrently with itself or other offload methods here on the same
* {@link SignalOffloader} instance.
*
* @param subscriber {@link Subscriber} for which the signals are to be offloaded.
* @param Type of items received by the passed and returned {@link Subscriber}.
* @return New {@link Subscriber} that will offload signals to the passed {@link Subscriber}.
*/
Subscriber offloadSubscriber(Subscriber subscriber);
/**
* Decorates the passed {@link SingleSource.Subscriber} such that all method calls to it will be offloaded.
* Caution
* This method MUST not be called concurrently with itself or other offload methods here on the same
* {@link SignalOffloader} instance.
*
* @param subscriber {@link SingleSource.Subscriber} for which the signals are to be offloaded.
* @param Type of items received by the passed and returned {@link SingleSource.Subscriber}.
* @return New {@link SingleSource.Subscriber} that will offload signals to the passed
* {@link SingleSource.Subscriber}.
*/
SingleSource.Subscriber offloadSubscriber(SingleSource.Subscriber subscriber);
/**
* Decorates the passed {@link CompletableSource.Subscriber} such that all method calls to it will be offloaded.
* Caution
* This method MUST not be called concurrently with itself or other offload methods here on the same
* {@link SignalOffloader} instance.
*
* @param subscriber {@link CompletableSource.Subscriber} for which the signals are to be offloaded.
* @return New {@link CompletableSource.Subscriber} that will offload signals to the passed
* {@link CompletableSource.Subscriber}.
*/
CompletableSource.Subscriber offloadSubscriber(CompletableSource.Subscriber subscriber);
/**
* Decorates the passed {@link Subscriber} such that all method calls to its {@link Subscription} will be offloaded.
* None of the {@link Subscriber} methods will be offloaded.
*
Caution
* This method MUST not be called concurrently with itself or other offload methods here on the same
* {@link SignalOffloader} instance.
*
* @param subscriber {@link Subscriber} for which the signals are to be offloaded.
* @param Type of items received by the passed and returned {@link Subscriber}.
* @return New {@link Subscriber} that will offload signals to the passed {@link Subscriber}.
*/
Subscriber offloadSubscription(Subscriber subscriber);
/**
* Decorates the passed {@link SingleSource.Subscriber} such that all method calls to its {@link Cancellable} will
* be offloaded.
* None of the {@link SingleSource.Subscriber} methods will be offloaded.
* Caution
* This method MUST not be called concurrently with itself or other offload methods here on the same
* {@link SignalOffloader} instance.
*
* @param subscriber {@link SingleSource.Subscriber} for which the signals are to be offloaded.
* @param Type of items received by the passed and returned {@link SingleSource.Subscriber}.
* @return New {@link SingleSource.Subscriber} that will offload signals to the passed
* {@link SingleSource.Subscriber}.
*/
SingleSource.Subscriber offloadCancellable(SingleSource.Subscriber subscriber);
/**
* Decorates the passed {@link CompletableSource.Subscriber} such that all method calls to its {@link Cancellable}
* will be offloaded.
* None of the {@link CompletableSource.Subscriber} methods will be offloaded.
* Caution LoadBalancerReadyHttpClientTest
* This method MUST not be called concurrently with itself or other offload methods here on the same
* {@link SignalOffloader} instance.
*
* @param subscriber {@link CompletableSource.Subscriber} for which the signals are to be offloaded.
* @return New {@link CompletableSource.Subscriber} that will offload signals to the passed
* {@link CompletableSource.Subscriber}.
*/
CompletableSource.Subscriber offloadCancellable(CompletableSource.Subscriber subscriber);
/**
* Offloads subscribe call for the passed {@link Subscriber}.
*
*
Offloading Failures
* Implementations are expected to handle failure to offload, e.g. If a thread pool is used to offload and it
* rejects task submissions. In such situations, it is expected that the passed {@link Subscriber} will be
* correctly terminated.
*
Caution
* This method MUST not be called concurrently with itself or other offload methods here on the same
* {@link SignalOffloader} instance.
*
* @param subscriber {@link Subscriber} for which subscribe call has to be offloaded.
* @param handleSubscribe {@link Consumer} to handle the offloaded subscribe call.
* @param Type of signal.
*/
void offloadSubscribe(Subscriber subscriber, Consumer> handleSubscribe);
/**
* Offloads subscribe call for the passed {@link Subscriber}.
*
* Offloading Failures
* Implementations are expected to handle failure to offload, e.g. If a thread pool is used to offload and it
* rejects task submissions. In such situations, it is expected that the passed {@link Subscriber} will be
* correctly terminated.
*
Caution
* This method MUST not be called concurrently with itself or other offload methods here on the same
* {@link SignalOffloader} instance.
*
* @param subscriber {@link SingleSource.Subscriber} for which subscribe call has to be offloaded.
* @param handleSubscribe {@link Consumer} to handle the offloaded subscribe call.
* @param Type of signal.
*/
void offloadSubscribe(SingleSource.Subscriber subscriber,
Consumer> handleSubscribe);
/**
* Offloads the subscribe call for the passed {@link Subscriber}.
*
* Offloading Failures
* Implementations are expected to handle failure to offload, e.g. If a thread pool is used to offload and it
* rejects task submissions. In such situations, it is expected that the passed {@link Subscriber} will be
* correctly terminated.
*
Caution
* This method MUST not be called concurrently with itself or other offload methods here on the same
* {@link SignalOffloader} instance.
*
* @param subscriber {@link Subscriber} for which for which subscribe call has to be offloaded.
* @param handleSubscribe {@link Consumer} to handle the offloaded subscribe call.
*/
void offloadSubscribe(CompletableSource.Subscriber subscriber,
Consumer handleSubscribe);
/**
* Offloads the consumption of the passed {@code signal} by the passed {@link Consumer}.
*
* Caution
* This method MUST not be called concurrently with itself or other offload methods here on the same
* {@link SignalOffloader} instance.
*
* @param signal {@code signal} to send to the {@link Consumer}.
* @param signalConsumer {@link Consumer} of the signal.
* @param Type of signal.
*/
void offloadSignal(T signal, Consumer signalConsumer);
}