core: rename up_to_date to needs_update in struct gpiod_line

This variable is called up_to_date which can lead readers to the wrong
conclusion that libgpiod can somehow know when external actors (such as
a different process or a kernel driver) change the state of a GPIO line.

This is not the case and libgpiod only ever knows if a line needs info
update when a previous internal call to gpiod_line_update() fails.

The kernel does not provide any notification mechanism currently.

For that reason: rename the variable to needs_update.

While at it: clarify the documentation for gpiod_line_needs_update().

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

diff --git a/include/gpiod.h b/include/gpiod.h
index 26794782e41a21ffa65ac8370e93d2a5d25b4b4b..9860ea8b474bf40a7519606180ac89a93bbd920d 100644 (file)
--- a/include/gpiod.h
+++ b/include/gpiod.h
@@ -742,10 +742,18 @@ int gpiod_line_update(struct gpiod_line *line) GPIOD_API;
  * The line is updated by calling gpiod_line_update() from within
  * gpiod_chip_get_line() and on every line request/release. However: an error
  * returned from gpiod_line_update() only breaks the execution of the former.
- * The request/release routines only set the internal up-to-date flag to false
+ * The request/release routines only set the internal needs_update flag to true
  * and continue their execution. This routine allows to check if a line info
  * update failed at some point and we should call gpiod_line_update()
  * explicitly.
+ *
+ * This routine will not indicate any potential changes introduced by external
+ * actors (such as a different process requesting the line). We currently have
+ * no mechanism provided by the kernel for that and for the sake of speed and
+ * simplicity of this low-level library we don't want to re-read the line info
+ * automatically everytime a property is retrieved. Any daemon using this
+ * library must track the state of lines on its own and call
+ * ::gpiod_line_update if needed.
  */
 bool gpiod_line_needs_update(struct gpiod_line *line) GPIOD_API;
 

diff --git a/lib/core.c b/lib/core.c
index 7ddb568f8885146931118091cc61c39dd9095363..a04514e689e2a9d2843608d3e2b5be25a656ecee 100644 (file)
--- a/lib/core.c
+++ b/lib/core.c
@@ -41,7 +41,7 @@ struct gpiod_line {
        bool open_drain;
 
        int state;
-       bool up_to_date;
+       bool needs_update;
 
        struct gpiod_chip *chip;
        struct line_fd_handle *fd_handle;
@@ -326,7 +326,7 @@ static void line_maybe_update(struct gpiod_line *line)
 
        rv = gpiod_line_update(line);
        if (rv < 0)
-               line->up_to_date = false;
+               line->needs_update = true;
 }
 
 struct gpiod_chip *gpiod_line_get_chip(struct gpiod_line *line)
@@ -376,7 +376,7 @@ bool gpiod_line_is_open_source(struct gpiod_line *line)
 
 bool gpiod_line_needs_update(struct gpiod_line *line)
 {
-       return !line->up_to_date;
+       return line->needs_update;
 }
 
 int gpiod_line_update(struct gpiod_line *line)
@@ -405,7 +405,7 @@ int gpiod_line_update(struct gpiod_line *line)
        strncpy(line->name, info.name, sizeof(line->name));
        strncpy(line->consumer, info.consumer, sizeof(line->consumer));
 
-       line->up_to_date = true;
+       line->needs_update = false;
 
        return 0;
 }