Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

clarify note on forcing thunks in the C API #10848

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
+1 −1
Open

clarify note on forcing thunks in the C API #10848

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
38616e9
clarify note on forcing thunks in the C API
fricklerhandwerk Jun 4, 2024
0d60bf0
reword
fricklerhandwerk Jun 5, 2024
e16d8f5
clarify
fricklerhandwerk Jun 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions src/libexpr-c/nix_api_expr.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,8 +129,7 @@ nix_err nix_value_call_multi(
*
* This function converts these Values into their final type.
*
* @note You do not need this function as long as you only use API calls that return a `Value`. This function is mainly
* needed before calling @ref getters.
* @note This function is called before calling `nix_get_type()` (and therefore before most other @ref getters), because lazy evaluation should be transparent to users.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* @note This function is called before calling `nix_get_type()` (and therefore before most other @ref getters), because lazy evaluation should be transparent to users.
* @note This function should be called before calling `nix_get_type()` (and therefore before most other @ref getters), because lazy evaluation should be transparent to users.

Otherwise it sounds a bit like we're describing what the bindings do. It is the reader's responsibility.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* @note This function is called before calling `nix_get_type()` (and therefore before most other @ref getters), because lazy evaluation should be transparent to users.
* @note You only need to call this function before `nix_get_type()` (and therefore before most other @ref getters), because lazy evaluation should be transparent to users of this API.

How about this then?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's not necessarily true. Suppose in your application you have a hardcoded Nix function, defined in a string literal, so you know how it behaves. For example:

# passed to nix_expr_eval_from_string

{ foo, bar }:
let
  # fancy application-specific computations are declared here
in
{
  inherit baz;
  n = builtins.length qux;
}

In such a case it's valid to

  1. call the function
  2. retrieve the n Value
  3. nix_value_force n
  4. not check the type, because we know its type statically
  5. call nix_get_int

Obviously a toy example, but this is a useful implementation pattern when you have a situation where a few things related things need to be computed by Nix and the application then reads the values it needs. Unlike individual function calls, you take advantage of shared computations this way.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, maybe I'm misunderstanding something big time here. Apparently it's not required to call it beforehand, but sometimes it is? But saying "you should" is not very informative - do you have to or not, what are the considerations exactly?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or maybe just delete the note if it's not gonna age well anyway.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i thought, "you need nix_value_force before any api function if and only if that api function does not return a Value" was a beautifully simple rule. is it wrong? will #10499 make it wrong? cc @roberth

*
* @param[out] context Optional, stores error information
* @param[in] state The state of the evaluation.
Expand Down
Loading