@@ -36,7 +36,8 @@ struct RunnerCommandJournalEntry {
3636enum RunnerCommandAdmission {
3737 /// Nothing is running for this id and nothing has finished: the caller owns the one execution.
3838 case execute
39- /// An execution is claimed and has not finished: the caller joins its outcome and runs nothing.
39+ /// An execution is claimed and has not finished: the caller runs nothing and is answered by that
40+ /// execution. `admit(command:registeringJoin:)` has already registered the send it gave this verdict.
4041 case join
4142 /// Execution finished, and the work reached the device: the caller answers from the journal and
4243 /// never executes this command again.
@@ -50,19 +51,44 @@ enum RunnerCommandAdmission {
5051final class RunnerCommandJournal {
5152 private let lock = NSLock ( )
5253 private let maxEntries = 64
54+ /// How many closed `commandId`s are remembered as bare ids once their entry is pruned. The window is
55+ /// 64x the entry window because a marker holds no outcome body, only the id.
56+ private let maxClosedCommandIds = 4096
5357 private let maxResponseJsonBytes = 16 * 1024
5458 private var entries : [ String : RunnerCommandJournalEntry ] = [ : ]
5559 private var order : [ String ] = [ ]
60+ /// Ids whose dispatched execution closed and whose entry has since been pruned: the admission half of
61+ /// what the entry recorded, kept without a body so bounded memory cannot make a spent id executable
62+ /// again. It settles admission only. `status` still answers `notAccepted` for such an id, because the
63+ /// outcome the entry held is gone and only the entry can report one.
64+ private var closedCommandIds : Set < String > = [ ]
65+ private var closedOrder : [ String ] = [ ]
5666
67+ /// Settles one send, and when the answer is to join a running execution, registers that send for the
68+ /// answer inside the same locked operation. No transition can close the entry between the two, which is
69+ /// what keeps a joined send from waiting on a delivery that already went out. `register` runs on the
70+ /// calling thread while the journal's lock is held: it may take a lock of its own, and must not call
71+ /// back into this journal. The wire route passes one; a caller that only reads the verdict — a journal
72+ /// test, or a probe that will not itself answer for the execution — leaves it unregistered and must not
73+ /// treat a `.join` verdict as a send that will be answered.
5774 @ discardableResult
58- func accept ( command : Command ) -> RunnerCommandAdmission {
75+ func accept (
76+ command : Command ,
77+ registeringJoin register : ( String ) -> Void = { _ in }
78+ ) -> RunnerCommandAdmission {
5979 guard let commandId = command . commandId ? . trimmedNonEmpty else { return . execute }
6080 lock . lock ( )
6181 defer { lock . unlock ( ) }
6282 guard let entry = entries [ commandId ] else {
83+ // The entry can be pruned; the fact it recorded is not, so an id that spent itself on the device
84+ // never executes again.
85+ if closedCommandIds . contains ( commandId ) {
86+ return . terminal ( outcome : alreadyFinishedRefusal ( command : command , commandId : commandId , outcomeDropped : true ) )
87+ }
6388 return claim ( command : command , commandId : commandId )
6489 }
6590 if ! entry . state . isTerminal {
91+ register ( commandId )
6692 return . join
6793 }
6894 // Nothing of this command ever reached the device, so the id carries no effect to protect and the
@@ -119,19 +145,6 @@ final class RunnerCommandJournal {
119145 )
120146 }
121147
122- /// The answer owed a send that joined an execution which has since closed: the outcome the runner
123- /// recorded, whether or not the work reached the device. Registering that send as a waiter instead
124- /// would leave it waiting on a delivery that already went out. `accept` answers a closed id on its own
125- /// terms, so this is narrower than admission.
126- func closedOutcome ( for command : Command ) -> Response ? {
127- guard let commandId = command . commandId ? . trimmedNonEmpty else { return nil }
128- lock . lock ( )
129- let entry = entries [ commandId ]
130- lock . unlock ( )
131- guard let entry , entry . state . isTerminal else { return nil }
132- return recordedOutcome ( for : entry )
133- }
134-
135148 func status ( normalizedCommandId commandId : String ) -> DataPayload {
136149 lock . lock ( )
137150 let entry = entries [ commandId ]
@@ -200,16 +213,26 @@ final class RunnerCommandJournal {
200213 pruneIfNeeded ( )
201214 }
202215
203- /// Drops the oldest closed entries. An entry whose execution is claimed but not finished is never
204- /// dropped, however deep the backlog: `status` answers `notAccepted` only for an id this journal does
205- /// not hold, and the daemon cannot read that as a safe terminal state — it would invalidate a session
206- /// whose runner is still executing the command it lost the answer to.
216+ /// Drops the oldest closed entries, keeping each one's id as the fact that settles admission for it.
217+ /// An entry whose execution is claimed but not finished is never dropped, however deep the backlog:
218+ /// `status` answers `notAccepted` only for an id this journal does not hold, and the daemon cannot read
219+ /// that as a safe terminal state — it would invalidate a session whose runner is still executing the
220+ /// command it lost the answer to.
207221 private func pruneIfNeeded ( ) {
208222 while order . count > maxEntries {
209223 guard let removable = order . first ( where : { entries [ $0 ] ? . state . isTerminal == true } ) else {
210224 return
211225 }
212226 order . removeAll { $0 == removable }
227+ // Only work that reached the device spends its id. A pruned refusal leaves the id free, which is
228+ // what the busy resend of the same `commandId` depends on (ADR 0005).
229+ if entries [ removable ] ? . dispatched == true {
230+ closedCommandIds . insert ( removable )
231+ closedOrder . append ( removable )
232+ while closedOrder . count > maxClosedCommandIds {
233+ closedCommandIds . remove ( closedOrder . removeFirst ( ) )
234+ }
235+ }
213236 entries . removeValue ( forKey : removable )
214237 }
215238 }
@@ -225,12 +248,36 @@ final class RunnerCommandJournal {
225248 if let error = entry . error {
226249 return Response ( ok : false , error : error )
227250 }
228- return Response (
251+ return alreadyFinishedRefusal (
252+ commandId : entry . commandId ,
253+ commandName : entry . command ,
254+ outcomeDropped : false
255+ )
256+ }
257+
258+ private func alreadyFinishedRefusal (
259+ command : Command ,
260+ commandId : String ,
261+ outcomeDropped : Bool
262+ ) -> Response {
263+ alreadyFinishedRefusal (
264+ commandId : commandId ,
265+ commandName : command . command . rawValue ,
266+ outcomeDropped : outcomeDropped
267+ )
268+ }
269+
270+ private func alreadyFinishedRefusal (
271+ commandId : String ,
272+ commandName : String ,
273+ outcomeDropped : Bool
274+ ) -> Response {
275+ Response (
229276 ok : false ,
230277 error : ErrorPayload (
231278 code : RunnerTests . RunnerWireErrorCode . commandAlreadyFinished ,
232279 message :
233- " The runner already finished \( entry . command ) with id \( entry . commandId ) and kept no response to replay. " ,
280+ " The runner already finished \( commandName ) with id \( commandId ) and kept no response to replay \( outcomeDropped ? " , because that record has since been dropped " : " " ) . " ,
234281 hint :
235282 " Read the screen with snapshot before sending anything else: the finished command's effect is already on the device. "
236283 )
0 commit comments