Interface MessageConnector.IMessageConnection
- Enclosing class:
MessageConnector
Receive demand counts complete messages. Each received callback consumes one credit, and callbacks for a connection must be delivered in message order. The provider leases the supplied storage until its release action is invoked, and must not mutate or reuse the storage before then. After a complete message has been accepted by the listener, the connector may grant more demand independently of when that message's Net4j buffer is released. Providers must retain each leased frame's storage until its matching release action.
A rejected send must not retain or access its buffer after returning and must not invoke its callback. An exception thrown before
acceptance has the same ownership result: the provider has not borrowed the buffer, must cease accessing it, and must not invoke its
callback. Acceptance is reported by returning true. Once the provider borrows the buffer, it must return true and
deliver exactly one terminal callback; the callback may happen before send(IBuffer, SendCallback) returns. A terminal callback
guarantees that provider access to the buffer has ended. Throwing after borrowing the buffer violates this contract; an accepted
send must return true and arrange its terminal callback. The provider must deliver
terminal callbacks for every accepted send, including sends outstanding during shutdown.
If a provider permanently omits a terminal callback, safe reuse and eventual reclamation of that buffer cannot both be guaranteed. The connector bounds this risk to at most one buffer for each connection generation. Repeated activations can therefore leave one retained buffer in each generation whose provider omitted completion; this is not a global one-buffer limit. The connector must not use timeouts or premature release to conceal the missing ownership transfer.
- Since:
- 4.23
- Author:
- Eike Stepper
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interfaceReceives connection readiness, complete inbound messages, writability, and closure.static interfaceReports completion of one accepted send. -
Method Summary
Modifier and TypeMethodDescriptionvoidabort()Initiates immediate termination, prevents further sends from being accepted, and causes outstanding accepted sends to complete unsuccessfully unless already successfully completed.voidStarts graceful local closure after all sends already accepted by the provider have completed.voidrequest(long messages) Grants demand for complete incoming messages.booleansend(IBuffer buffer, MessageConnector.IMessageConnection.SendCallback callback) Attempts to send one complete framed buffer.voidInstalls a listener and begins or attaches the connection.
-
Method Details
-
start
Installs a listener and begins or attaches the connection. Implementations may callMessageConnector.IMessageConnection.Listener.ready()synchronously. A listener belongs to this connection generation and must not be used to signal readiness or input for another generation.- Parameters:
listener- the callbacks for this connection generation
-
send
Attempts to send one complete framed buffer. At most one accepted send is submitted by aMessageConnectorat a time. Returningfalserejects the send: the provider must not borrow, retain, modify, release, or later access the buffer, and must not invoke the callback. Throwing before acceptance has the same ownership result and the provider must no longer access the buffer. Acceptance is reported by returningtrue; once the provider borrows the buffer, it must returntrueand deliver exactly one terminal callback, including after transport failure. Throwing after borrowing violates this contract; the provider must returntrueand arrange that accepted-send completion. All provider access to borrowed storage must have ended before the terminal callback.- Parameters:
buffer- the Net4j buffer borrowed for the sendcallback- completion of an accepted send- Returns:
truewhen accepted with exactly one terminal callback, orfalsewhen rejected without borrowing the buffer
-
request
void request(long messages) Grants demand for complete incoming messages. Each delivered message consumes one credit. The provider must not deliver more messages than requested and must retain each supplied storage lease until the listener invokes its matching release action. The connector may grant further demand while earlier messages remain leased.- Parameters:
messages- positive number of additional messages requested
-
closeGracefully
void closeGracefully()Starts graceful local closure after all sends already accepted by the provider have completed. Once closure begins, the provider rejects new sends and later reports closure through its listener. -
abort
void abort()Initiates immediate termination, prevents further sends from being accepted, and causes outstanding accepted sends to complete unsuccessfully unless already successfully completed. This method is safe concurrently withsend(IBuffer, SendCallback)and must not wait indefinitely for callbacks. Borrowed buffers remain owned by the provider until their terminal callbacks, which may occur after this method returns.
-