Documentation for reference counting behaviour of jv functions
Author: mwilliamsonCreated Jul 10, 2026Updated Jul 10, 2026
Hello! I'm the author of a set of Python bindings for jq, and I'm doing a quick audit of jv values to make sure they're freed appropriately. To do so requires knowing when jv functions do and don't consume their inputs.
In jv.h, the behaviour is described as:
/*
* All jv_* functions consume (decref) input and produce (incref) output
* Except jv_copy
*/However, I think there are several jv functions that don't consume their input, such as jv_get_kind and jv_string_value. At the moment, so far as I can tell, the only way to find out if a function consumes its input or not is to read its source code.
Assuming my understanding is correct, perhaps it would be worth adding documentation for each of the jv functions to describe whether or not they consume their inputs?
Source: jqlang/jq