Skip to content

stmrecall

Restores a saved state of a runner.

The state must have been saved with stmcall.

Syntax

kdone = stmrecall(irunner, Sname, ktrig)

kdone stmrecall irunner, Sname, ktrig

Initialization

irunner -- a runner handle, returned by stminstance.

Performance

Sname -- the name of a saved state. An unknown name causes a performance error.

ktrig -- the action happens when ktrig becomes greater than 0, that is on the first pass where it is positive after being 0 or less. A trigger that is positive on the very first pass also counts. Holding ktrig high does not repeat the action.

kdone -- 1 on the pass where the state is restored, 0 otherwise.

Recalling restores the current node, the previous node, the pending request and the clock. It is recorded as an event (kind 4). If it changes the current node, it also counts as a transition for stmonenter and stmonexit; a recall that lands on the current node does not fire them. The event history, the saved states and the paused state are not changed.

stmrecall is ignored while the runner is paused or deleted.

This opcode changes the runner, so it counts as a writer: a runner accepts writers from one instrument instance at a time. See Writers and observers.

Examples

A runner walks a chain of sections, one per control period. Its state at Verse is saved with stmcall and restored twice with stmrecall, so the walk from Verse is repeated with the same node and the same clock. It uses the file stm-checkpoint.csd.

Saving and restoring the state of a runner.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
<CsoundSynthesizer>
<CsOptions>
-n -d -m0
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 480
nchnls = 1
0dbfs = 1

; stmcall saves the state of a runner under a name, stmrecall brings it
; back. The runner walks a chain of sections, one per control period.
; The state at "Verse" is saved, and recalled twice from "Outro", so the
; walk from "Verse" is repeated with the same node and the same clock.
; A name works as a save slot: each save under "verse" replaces the last.

builder:i = stmcreate()
stmaddnode(builder, "Intro")
stmaddnode(builder, "Verse")
stmaddnode(builder, "Chorus")
stmaddnode(builder, "Outro")
stmaddedge(builder, "Intro", "Verse")
stmaddedge(builder, "Verse", "Chorus")
stmaddedge(builder, "Chorus", "Outro")
gi_runner@global:i = stminstance(stmcompile(builder))

instr 1
  r:i = gi_runner
  cycle:k init 0
  cycle += 1

  node:S = stmcurrent(r)
  tick:k = stmtick(r)

  ; save each time the walk is on Verse (the trigger rises on every pass)
  saved:k = stmcall(r, "verse", strcmpk(node, "Verse") == 0 ? 1 : 0)

  ; one step along the chain per control period
  if strcmpk(node, "Intro") == 0 then
    stmnext(r, "Verse")
  elseif strcmpk(node, "Verse") == 0 then
    stmnext(r, "Chorus")
  elseif strcmpk(node, "Chorus") == 0 then
    stmnext(r, "Outro")
  endif

  status:k, from:k, to:k = stmadvance(r)

  ; at Outro, go back to the saved state, but only twice
  repeats:k init 0
  recall:k = 0
  if strcmpk(node, "Outro") == 0 && repeats < 2 then
    recall = 1
    repeats += 1
  endif
  restored:k = stmrecall(r, "verse", recall)

  printks("cycle %2d  tick %d  %-6s  saved %d  restored %d  -> %s\n", 0, \
          cycle, tick, node, saved, restored, stmcurrent(r))
endin
</CsInstruments>
<CsScore>
i 1 0 0.10
e
</CsScore>
</CsoundSynthesizer>

Its output is:

cycle  1  tick 0  Intro   saved 0  restored 0  -> Verse
cycle  2  tick 1  Verse   saved 1  restored 0  -> Chorus
cycle  3  tick 2  Chorus  saved 0  restored 0  -> Outro
cycle  4  tick 3  Outro   saved 0  restored 1  -> Verse
cycle  5  tick 1  Verse   saved 1  restored 0  -> Chorus
cycle  6  tick 2  Chorus  saved 0  restored 0  -> Outro
cycle  7  tick 3  Outro   saved 0  restored 1  -> Verse
cycle  8  tick 1  Verse   saved 1  restored 0  -> Chorus
cycle  9  tick 2  Chorus  saved 0  restored 0  -> Outro
cycle 10  tick 3  Outro   saved 0  restored 0  -> Outro

The trigger of stmcall rises on every pass through Verse, so "verse" is saved again in cycles 5 and 8; each save replaces the previous one, here with the same state. Each recall restores the node and the tick count, so the walk from Verse repeats exactly.

See also

State Machine Graphs

stmcall, stmreset

Credits

Author: Pasquale Mainolfi
Italy
New in Csound version 7.0
October 2026