From 4e1e0e21c3d797066f4152e73019eb72ff9c88a5 Mon Sep 17 00:00:00 2001 From: Alexander Momchilov Date: Mon, 16 Sep 2024 09:45:23 -0400 Subject: [PATCH] Document lifetime of `pm_options_t` --- include/prism.h | 5 +++++ include/prism/options.h | 4 ++++ 2 files changed, 9 insertions(+) diff --git a/include/prism.h b/include/prism.h index 755c38fca2..9dab3cea99 100644 --- a/include/prism.h +++ b/include/prism.h @@ -48,11 +48,13 @@ PRISM_EXPORTED_FUNCTION const char * pm_version(void); /** * Initialize a parser with the given start and end pointers. + * The resulting parser must eventually be freed with `pm_parser_free()`. * * @param parser The parser to initialize. * @param source The source to parse. * @param size The size of the source. * @param options The optional options to use when parsing. + * These options must live for the whole lifetime of this parser. */ PRISM_EXPORTED_FUNCTION void pm_parser_init(pm_parser_t *parser, const uint8_t *source, size_t size, const pm_options_t *options); @@ -68,6 +70,9 @@ PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_changed_callback(pm_par /** * Free any memory associated with the given parser. * + * Note: this does not free the `pm_options_t` object that was used to initialize the parser. + * See \ref pm_options_t::pm_options_free() "pm_options_free()". + * * @param parser The parser to free. */ PRISM_EXPORTED_FUNCTION void pm_parser_free(pm_parser_t *parser); diff --git a/include/prism/options.h b/include/prism/options.h index 3cb7304951..d7c8415681 100644 --- a/include/prism/options.h +++ b/include/prism/options.h @@ -303,6 +303,10 @@ PRISM_EXPORTED_FUNCTION const pm_string_t * pm_options_scope_local_get(const pm_ /** * Free the internal memory associated with the options. * + * Must be called after the parser was freed with \ref pm_parser::pm_parser_free() "pm_parser_free()". + * If multiple parsers are created with the same options object, they must all be freed first, + * before it is safe to free the options object. + * * @param options The options struct whose internal memory should be freed. */ PRISM_EXPORTED_FUNCTION void pm_options_free(pm_options_t *options);