Skip to content

feat: Add argreader utility#171

Draft
jake-arkinstall wants to merge 7 commits into
mainfrom
feat/sample-utility
Draft

feat: Add argreader utility#171
jake-arkinstall wants to merge 7 commits into
mainfrom
feat/sample-utility

Conversation

@jake-arkinstall
Copy link
Copy Markdown
Collaborator

Presently we have no examples of utilities that can be used with Selene.

This PR adds one - an argument reader, that can be used to provide runtime parameters into the user program.

When building using the ArgReaderPlugin, user code gains access to the following functions:

bool argreader_get_bool(char const* tag);
uint64_t argreader_get_u64(char const* tag);
int64_t argreader_get_i64(char const* tag);
double argreader_get_f64(char const* tag);
void argreader_get_bool_array(char const* tag, bool* out, uint64_t result);
void argreader_get_u64_array(char const* tag, uint64_t* out, uint64_t result);
void argreader_get_i64_array(char const* tag, int64_t* out, uint64_t result);
void argreader_get_f64_array(char const* tag, double* out, uint64_t result);

Note that the tag strings follow the same format as result() and panic() in that they start with a length byte, must be utf-8, and are not required to be null-terminated. As such, their maximum length is 255 characters. They do not require namespacing (e.g. "USER:INT:" in the result stream), but this may be added as long as the arguments are provided with the same namespacing. Error handling is handled internally and will result in descriptive panics.

The user then runs selene within a context manager:

arg_provider = ArgProvider()
arg_provider.set_constant_args(
    foo=True,
    bar=3.14159265359,
    baz=[8, 2, 5, 4, 1],
)
# there is also arg_provider.set_variable_args(args: list[dict])
# for per-shot args
with arg_provider:
    shots = instance.run_shots(...)

which writes parameters to a temporary YAML file, then sets the environment variable SELENE_ARGREADER_INPUT_FILE to point to this file. When the user program is running and a parameter is read for the first time, this yaml file is parsed with Serde and stored in memory. Arguments are extracted based on the current shot.

The ability to export utility calls to the selene Trace is also added, and ArgReader utilises this to provide each parameter's type and value upon read. In general this trace export provides additional insight into the order that things happen within a run, and allows for utilities making custom calls to log their activity.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant