001/*
002 * Copyright 2022-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.soklet;
018
019import org.jspecify.annotations.NonNull;
020
021import javax.annotation.concurrent.ThreadSafe;
022
023import static java.util.Objects.requireNonNull;
024
025/**
026 * Framework-owned capability loaned to one attached transport member for
027 * recording its independent failure and affirmative termination proof. The
028 * transport may retain the signal after {@code attach(...)} returns, but must
029 * not share it with an unrelated transport member or lifecycle. Soklet owns the
030 * recorded state and all completion derived from it; the transport can only
031 * report observations through the methods below.
032 * <p>
033 * A failure or termination proof reported before the lifecycle owner's
034 * shutdown intent is independent premature termination, including before
035 * readiness. For a synchronous {@link TransportRuntime#start(StartupContext)}
036 * failure, throw from start and let the owner deliver rollback phases; report
037 * proof after their cleanup ends. Do not delay a separate worker's failure
038 * signal merely because startup is still running.
039 *
040 * @author <a href="https://www.revetkn.com">Mark Allen</a>
041 */
042@ThreadSafe
043public final class TransportTerminationSignal {
044        @NonNull
045        private final InternalTransportTerminationSignal internalSignal;
046
047        TransportTerminationSignal(
048                        @NonNull InternalTransportTerminationSignal internalSignal) {
049                this.internalSignal = requireNonNull(internalSignal);
050        }
051
052        /**
053         * Records affirmative proof after every activity owned by this member ends.
054         * Repeated calls are idempotent. This remains legal after
055         * {@link #signalTerminationFailure(Throwable)} so a failure can later be
056         * paired with definitive termination proof.
057         * <p>
058         * Returning from a shutdown method, closing admission, or merely requesting
059         * cancelation is not sufficient proof while member-owned work remains.
060         */
061        public void signalTerminated() {
062                this.internalSignal.signalTerminated();
063        }
064
065        /**
066         * Records the first failure without claiming termination proof. Repeated
067         * calls are safe and do not replace the first recorded failure; callers may
068         * subsequently invoke {@link #signalTerminated()} when proof becomes true.
069         * Reporting a failure does not transfer resource ownership to Soklet and does
070         * not claim that member-owned activity has ended.
071         *
072         * @param cause exact failure cause
073         */
074        public void signalTerminationFailure(@NonNull Throwable cause) {
075                this.internalSignal.signalTerminationFailure(requireNonNull(cause));
076        }
077}