From def9636d01094a81a71ebd181169fb18d2b9c23d Mon Sep 17 00:00:00 2001 From: Justin Viiret Date: Tue, 7 Nov 2017 11:48:46 +1100 Subject: [PATCH] doc: document that hs_close_stream frees memory Add explicit documentation that hs_close_stream() will free the stream state after returning any matches. --- src/hs_common.h | 4 ++++ src/hs_runtime.h | 10 ++++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/src/hs_common.h b/src/hs_common.h index e1f079f2..3d79a6fa 100644 --- a/src/hs_common.h +++ b/src/hs_common.h @@ -479,6 +479,10 @@ hs_error_t HS_CDECL hs_valid_platform(void); /** * A parameter passed to this function was invalid. + * + * This error is only returned in cases where the function can detect an + * invalid parameter -- it cannot be relied upon to detect (for example) + * pointers to freed memory or other invalid data. */ #define HS_INVALID (-1) diff --git a/src/hs_runtime.h b/src/hs_runtime.h index 98e50068..c979bb8c 100644 --- a/src/hs_runtime.h +++ b/src/hs_runtime.h @@ -193,6 +193,12 @@ hs_error_t HS_CDECL hs_scan_stream(hs_stream_t *id, const char *data, /** * Close a stream. * + * This function completes matching on the given stream and frees the memory + * associated with the stream state. After this call, the stream pointed to by + * @a id is invalid and can no longer be used. To reuse the stream state after + * completion, rather than closing it, the @ref hs_reset_stream function can be + * used. + * * This function must be called for any stream created with @ref * hs_open_stream(), even if scanning has been terminated by a non-zero return * from the match callback function. @@ -404,8 +410,8 @@ hs_error_t HS_CDECL hs_expand_stream(const hs_database_t *db, * if these properties are not satisfied. * * @param to_stream - * A pointer to the generated @ref hs_stream_t will be - * returned; NULL on failure. + * A pointer to a valid stream state. A pointer to the expanded @ref + * hs_stream_t will be returned; NULL on failure. * * @param buf * A compressed representation of a stream. These compressed forms are