Skip to content

destroy

Destroys an embedded Csound engine at initialization.

Use destroy when you have finished with a temporary Csound object and want to release it during initialization, before the containing instrument ends.

Syntax

destroy(engine)

destroy engine

Initialization

engine is a Csound object made with engine:Csound = create(). It holds a separate Csound engine inside the running one.

destroy has no output. It destroys that engine and frees any audio buffers allocated for it. The containing Csound engine keeps running.

For a Csound object, delete performs the same cleanup when the containing instrument ends, including any release extension. destroy performs it when execution reaches the call during initialization. It has no performance-time form.

Destroy each engine only once. Do not also call delete for it, and stop using every reference to it after destruction. Copying a Csound object variable shares the engine rather than creating another one.

destroy accepts only a Csound object. See delete for cleanup of Instr, InstrDef and Opcode objects.

Examples

You can check whether a generated instrument definition compiles in a temporary engine without adding it to the main orchestra. This example destroys the temporary engine as soon as compilation returns, then reports the saved result. It does not start or perform the temporary engine.

It uses destroy.csd.

Discard an engine after checking an instrument definition
 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
<CsoundSynthesizer>
<CsOptions>
-n -d -m0
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 1
0dbfs = 1

instr CheckCode
  SCode = {{
    instr Candidate
      aTone = oscili(0.1, 440)
      out(aTone)
    endin
  }}

  // Compile the definition in a separate engine.
  engine:Csound = create()
  iResult = compilestr(engine, SCode)

  // We only need the result, so release the engine now.
  destroy(engine)

  // iResult belongs to this instrument and remains available.
  if iResult == 0 then
    prints("The instrument definition compiled successfully.\n")
  else
    prints("The instrument definition could not be compiled.\n")
  endif
endin
</CsInstruments>
<CsScore>
i "CheckCode" 0 0.1
e
</CsScore>
</CsoundSynthesizer>

See also

delete, compilestr, Instrument definitions, instances and opcode objects

Credits

Author Victor Lazzarini, 2025.

New in Csound 7.