From aa5eff6b8580cfbf899b91db2d86f1fcdcb45192 Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Sat, 10 Oct 2026 18:34:47 -0600 Subject: [PATCH] [docs] Qualify the object constructor failure guarantee (#6364) The lifecycle chapter claimed that all constructors return empty singletons on failure. Constructors ending in _or_fail instead return NULL, including the established blob constructors. Describe both conventions and require checking _or_fail results. Validated the XML and reproduced the blob constructor behavior with a nonexistent file and an oversized blob. Documentation only. Fixes: https://github.com/harfbuzz/harfbuzz/issues/6359 Assisted-by: Codex --- docs/usermanual-object-model.xml | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/usermanual-object-model.xml b/docs/usermanual-object-model.xml index 7d70c95c1..5faf8f4dc 100644 --- a/docs/usermanual-object-model.xml +++ b/docs/usermanual-object-model.xml @@ -172,11 +172,15 @@ they will need to make a duplicate of the original. - Finally, object constructors (and, indeed, as much of the - shaping API as possible) will never return - NULL. Instead, if there is an allocation - error, each constructor will return an “empty” object - singleton. + Finally, most object constructors return an “empty” object + singleton on allocation failure rather than + NULL. Constructors whose names end in + _or_fail, such as + hb_blob_create_or_fail() and + hb_blob_create_from_file_or_fail(), instead + return NULL on failure. Check their return + values before using the objects, and consult each constructor's + API Reference documentation for its failure behavior. These empty-object singletons are inert and safe (although