--- description: 'How the ABR SDK manages object lifetimes: the context manager pattern, close(), and how child resources are cleaned up.' --- # SDK lifecycle Every ABR SDK object wraps a native handle. Releasing that handle correctly is the caller's responsibility. This page explains how object lifetimes work, the recommended pattern for releasing them, and what happens to child resources when a parent is closed. ## Handles and their owners ::::{lang-set} :::{lang} python {api}`Application` is the base class for all ABR runtime objects. When you use ASR, you create an {api}`Asr` instance; when you use TTS, you create a {api}`Tts` instance. Both inherit from {api}`Application`. You rarely interact with {api}`Application` directly. Its lifecycle methods ({api}`Application.close` and {api}`Application.create_event_set`) are inherited by {api}`Asr` and {api}`Tts` and behave the same way on any instance. ::: :::{lang} c The C binding has two handles with a lifetime of their own. An {c:struct}`abr_lib` is the loaded shared library of an application package; {c:func}`abr_lib_open` fills it and {c:func}`abr_lib_close` unloads it. An {c:type}`abr_app_t` is an application instance, ASR or TTS, created from that library with {c:member}`abr_lib.app_create` and freed with {c:member}`abr_lib.app_free`. Every other handle is a child of the application. ::: :::: ## The recommended pattern ::::{lang-set} :::{lang} python The recommended way to use any ABR object is inside a `with` block: ```{example} recommended.py ``` When the `with` block exits, Python calls {api}`Application.__exit__`, which calls {api}`Application.close`. This happens on both normal exit and on exceptions. The `with` block is the safest pattern because cleanup is guaranteed even if your code raises partway through. The same applies to {api}`Tts`; use a `with` block and {api}`Application.close` is called automatically on exit. ::: :::{lang} c Open the library, create the application, use it, free the application, then close the library. Buffers, event sets and events do not need to be released separately: ```{example} recommended.c ``` Free the application before closing the library: `app_free` is a function inside the library, and `abr_lib_close` unloads it. `abr_lib_open` resets the struct whether or not it succeeds, and `abr_lib_close` on an already closed struct has no effect, so a cleanup path can call it unconditionally. ::: :::: ## What closing does ::::{lang-set} :::{lang} python {api}`Application.close` releases the native handle and all child resources. The sequence is the same for {api}`Asr` and {api}`Tts`: 1. Any in-progress session is closed. 2. All {api}`EventSet` objects owned by the application are closed, which closes their associated {api}`Event` objects. 3. The native application handle is freed. After {api}`Application.close` returns, calling any method on the object raises `abr_sdk.exceptions.AbrSdkError`, a subclass of the built-in `RuntimeError`. Calling {api}`Application.close` a second time has no effect. ::: :::{lang} c {c:member}`abr_lib.app_free` releases the application and all child resources, in the same order for ASR and TTS: 1. Any in-progress session is closed. 2. All {c:type}`abr_evset_t` objects created from the application are freed, along with their {c:type}`abr_event_t` objects. 3. The native application handle is freed. The buffers {c:member}`abr_lib.app_get_buffer` returned, and every event set and event, are invalid afterwards. Passing `NULL` is allowed and does nothing. The `session.h` helper's `abr_session_close` runs the whole sequence and is also safe to call twice. ::: :::: ## Closing explicitly ::::{lang-set} :::{lang} python When a context manager is not practical, for example when an {api}`Asr` or {api}`Tts` instance is owned by a longer-lived class, call {api}`Application.close` explicitly: ```{example} explicit_close.py ``` Call {api}`Application.close` before the object goes out of scope. If {api}`Application.close` is never called, the native handle will not be freed until the process exits. The same pattern applies to {api}`Tts`. ::: :::{lang} c When a longer-lived struct owns an application, give it an init and a shutdown function and call the latter before the struct goes out of scope. If it is never called, the native handle is not freed until the process exits: ```{example} explicit_close.c ``` ::: :::: :::{admonition} Next steps :class: hint - {doc}`/sdk/concepts/streaming-and-chunks`: how {api}`EventSet`, {api}`Event`, and {api}`Buffer` work together underneath the high-level API. - {api}`Asr`: full method reference for {api}`Application.close`, {api}`Asr.push`, and {api}`Asr.wait_for_completion`. - {api}`Tts`: full method reference for {api}`Application.close` and TTS synthesis methods. :::