A lightweight message-passing actor for concurrent state management. Each actor has a dedicated thread that processes messages sequentially from a queue. This guarantees that the actor's state is never accessed concurrently — no locks needed. Two factory patterns provide the common shapes: <
| 88 | * @since 6.0.0 |
| 89 | */ |
| 90 | public interface Actor<T> extends AutoCloseable { |
| 91 | |
| 92 | /** |
| 93 | * Sends a message to this actor. The message is queued and processed |
| 94 | * asynchronously. Fire-and-forget — no reply is expected. |
| 95 | * <p> |
| 96 | * Bounded-mailbox interaction (see {@link ActorOptions.Overflow}): |
| 97 | * <ul> |
| 98 | * <li>{@link ActorOptions.Overflow#BLOCK BLOCK}: the calling thread |
| 99 | * blocks until queue capacity is available, then enqueues.</li> |
| 100 | * <li>{@link ActorOptions.Overflow#FAIL FAIL}: throws |
| 101 | * {@link IllegalStateException} when the mailbox is full.</li> |
| 102 | * <li>{@link ActorOptions.Overflow#DROP_NEWEST DROP_NEWEST}: the |
| 103 | * message is <em>silently dropped</em> — there is no reply |
| 104 | * to carry the failure, so a fire-and-forget overflow is |
| 105 | * invisible to the sender. If you need drop visibility, |
| 106 | * prefer {@link #sendAndGet} (which binds the dropped |
| 107 | * reply to {@link IllegalStateException}) or a different |
| 108 | * overflow policy.</li> |
| 109 | * </ul> |
| 110 | * |
| 111 | * @param message the message to send |
| 112 | * @throws IllegalStateException if the actor has been stopped, or if |
| 113 | * the mailbox is bounded with {@link ActorOptions.Overflow#FAIL} |
| 114 | * and is full |
| 115 | */ |
| 116 | void send(T message); |
| 117 | |
| 118 | /** |
| 119 | * Sends a message and returns an {@link Awaitable} that completes |
| 120 | * with the reply. For reactors, the reply is the handler's return |
| 121 | * value. For stateful actors, the reply is the new state. |
| 122 | * <p> |
| 123 | * Bounded-mailbox interaction (see {@link ActorOptions.Overflow}): |
| 124 | * <ul> |
| 125 | * <li>{@link ActorOptions.Overflow#BLOCK BLOCK}: the calling thread |
| 126 | * blocks until queue capacity is available, then enqueues.</li> |
| 127 | * <li>{@link ActorOptions.Overflow#FAIL FAIL}: throws |
| 128 | * {@link IllegalStateException} when the mailbox is full.</li> |
| 129 | * <li>{@link ActorOptions.Overflow#DROP_NEWEST DROP_NEWEST}: returns |
| 130 | * an {@code Awaitable} that completes exceptionally with |
| 131 | * {@link IllegalStateException} indicating the message was |
| 132 | * dropped; the handler is never invoked.</li> |
| 133 | * </ul> |
| 134 | * |
| 135 | * @param message the message to send |
| 136 | * @param <R> the reply type |
| 137 | * @return an awaitable reply |
| 138 | * @throws IllegalStateException if the actor has been stopped, or if |
| 139 | * the mailbox is bounded with {@link ActorOptions.Overflow#FAIL} |
| 140 | * and is full |
| 141 | */ |
| 142 | <R> Awaitable<R> sendAndGet(T message); |
| 143 | |
| 144 | /** |
| 145 | * Returns {@code true} while the actor is accepting new sends. |
| 146 | * <p> |
| 147 | * The actor lifecycle has three states, expressed via this method |
no outgoing calls
no test coverage detected