Closing context handles
The mm-renderer configuration determines whether client applications can obtain additional handles to existing contexts as well as how mm-renderer behaves when closing context handles.
Handles obtained by opening existing contexts are called secondary handles, whereas the handle obtained by creating a context is called the primary handle.
The configuration may allow contexts to exist after their primary handles have been
closed. These are called orphan contexts. When such contexts are allowed,
secondary handles are also allowed; however, secondary handles may be allowed when
orphan contexts aren't. For clarification, see the descriptions of the
-c and -o options in
Command line for mm-renderer
.
- If orphan contexts are allowed, the only way to close the primary context handle without destroying the context is by calling mmr_context_close().
- If orphan contexts aren't allowed, there's no way to close the primary handle without destroying the context. In this case, calling mmr_context_close() with the primary handle is equivalent to calling mmr_context_destroy() because mm-renderer will not only close the context handle but will also stop playback, detach any inputs and outputs, and destroy the context. Therefore, you must ensure that any secondary handles, if permitted, are properly closed.
- Regardless of the configuration, if your application terminates unexpectedly or disconnects from mm-renderer (with mmr_disconnect()) without explicitly closing the primary handle, the context is destroyed. Note that mmr_disconnect() actually closes all context handles associated with the connection handle.