Microsoft DirectX 9.0 SDK Update (October 2004)

Cache Management

When an object is cached, the same instance of the object is always returned by the IDirectMusicLoader8::GetObject method.

The cache stores a pointer to the object. The memory for the object itself is managed by COM, and is not released until the reference count reaches zero. It is important to remember that clearing an object from the cache is not the same as releasing your application's COM reference to it.

Caching is used extensively in the file-loading process to resolve links to objects. For example, two segments could reference the same style. When the first segment loads, it calls the loader to get the style. The loader creates a style object, loads the data from disk, caches a pointer to the style object, and returns this pointer to the segment. If caching is enabled, when the second segment loads, it asks for the style, and the loader immediately returns the same pointer. Now both segments point to the same style. If caching is disabled, the second segment's request for the style causes a duplicate style object to be loaded from the file, at a cost in time and memory.

Here's another example. A band object relies on the loader to keep the General MIDI DLS collection cached. Every time a band has to download a GM instrument, it gets the collection from the loader. If caching for CLSID_DirectMusicCollection is disabled, every patch change in a MIDI file causes a separate copy of the entire GM collection to be created. This is obviously undesirable.

By default, caching is enabled for all object classes. You can disable caching for an object class, or for all objects, by using the IDirectMusicLoader8::EnableCache method. This method can also be used to re-enable caching for any or all object classes.

If you want to clear the cache without disabling future caching, use the IDirectMusicLoader8::ClearCache method. It's not necessary to call this method before terminating your application, because the cache is automatically cleared when the loader is released. ClearCache is only useful if the application soundtrack is changing completely, with all new instruments and source files.

Note Regardless of whether caching is enabled, the loader keeps a private cache of object descriptors. When you load an object from a stream, a reference to the IStream is cached with the descriptor, and if that object is subsequently reloaded, it will be loaded from the same stream. When you load an object from a memory location, the address and buffer size are cached, and if the address is subsequently reused for another object, the incorrect number of bytes might be loaded. To ensure that the private cache of object descriptors is cleared, you can do one of the following:

If caching is enabled, call ClearCache.
If caching is not enabled, either destroy the loader and create a new one, or call IDirectMusicLoader8::SetSearchDirectory with the fClear parameter set to TRUE.

To cache a single object when general caching is disabled, pass it to the IDirectMusicLoader8::CacheObject method.

You can remove an object from the cache, ensuring that it will be loaded again on the next call to GetObject, by using the IDirectMusicLoader8::ReleaseObject or IDirectMusicLoader8::ReleaseObjectByUnknown method. It is a good idea to call one of these methods before calling Release on an object, especially a segment. If you don't, a reference to the object remains in the cache, so the object continues to exist. As well as taking up memory, the object might retain certain state information. In the case of a segment, any instance that you load later will be taken from the cache, and the start point and loop points will be the same as they were when the previous instance was destroyed.

See Also