# AbandonInstrument

Make an instrument available for adoption.

### Synopsis

`Err AbandonInstrument (Item Instrument)`

### Description

This function together with `AdoptInstrument()` form a simple, but efficient, voice allocation system for a single instrument Template. `AbandonInstrument()` adds an instrument to a pool of unused instruments; `AdoptInstrument()` allocates instruments from that pool. A Template's pool can grow or shrink dynamically.

Why should you use this system when `CreateInstrument()` and `DeleteInstrument()` also do dynamic voice allocation? The answer is that `CreateInstrument()` and `DeleteInstrument()` create and delete Items and allocate and free DSP resources. `AdoptInstrument()` and `AbandonInstrument()` manage a pool of already existing Instrument Items belonging to a template. Therefore they don't have the overhead of Item creation and DSP resource management, and don't thrash the Item table.

This function stops the instrument, if it was running, and sets its status to AF_ABANDONED (see `GetAudioItemInfo()` AF_TAG_STATUS). This instrument is now available to be adopted from its Template by calling AdoptInstrument().

Instruments created with the AF_INSF_AUTOABANDON flag set, are automatically put into the AF_ABANDONED state when stopped.

### Arguments

Instrument
  The item number for the instrument to abandon.

### Return Value

The function returns a non-negative value if successful or an error code (a negative value) if an error occurs.

### Implementation

SWI implemented in Audio folio V20.

### Associated Files

audio.h

### See Also

``AdoptInstrument`(), StopInstrument(), ScavengeInstrument(), GetAudioItemInfo(), Instrument`