PetWay progress: a step towards PetLang: revised calling conventions

2025-07-02

Initially PetWay was designed to facilitate programming in C, but the ultimate goal is to make it a runtime for PetLang. This milestone is a step towards calling conventions required for threaded code.

Changes

• Dropped PwResult in favor of bool return value and optional result argument.
  • Result is a pointer to any type for now. For example, for tell and seek functions the result type is off_t*.
  • Eventually result will be a pointer to function-specific result structure.
  • Result is the last argument except for functions that accept variadic arguments.
  • Result is NOT guaranteed to be Null upon function call. Function must call pw_destroy before assigning it.
• Added Task structure. Currently it has only one field status. This field is updated when a function returns false. When a function returns true, the status should be set to PW_SUCCESS, but for now it is unchanged.
• Status type is no longer special for maps and arrays. But is is still special for variadic functions.
• Variadic arguments of PwValue type are always passed by value. They can't be passed by pointer anymore.
• CharPtr's clone no longer converts to string.

Interfacing with C

Some functions still return PwValue: pw_clone and variadic functions.

Variadic functions are extremely convenient for expressing maps and arrays in C, but functions no longer return PwResult. As a workaround, pwva macro was added. It exploits GNU extension statement expression and returns either result or status, depending on function's return value. If an error occurs when some variadic argument is pushed on stack, it is impossible to handle such an error during function call. These errors are handled by variadic function that checks arguments. Arguments are always passed by value and variadic function is responsible for destroying them upon return.

pw_get and pw_map_get are confusing because the result is the first argument for the former and is the last argument for the latter.

What helps to avoid common mistakes

• [[nodiscard]] attribute for functions, this ensures the boolean return value is always checked.
• Calling pw_destroy for the destination in pw_move and pw_clone2.
• Cleanup attribute for PwValue.

What caused segfaults

• Uninitialized PwValue variable that receives result. In PetLang all variables will be initialized unless specifically declared as uninitialized (TBD)

Future work

Finish Pet Preprocessor's initial task: facilitate definition of per-function arguments and result structures.

Rewrite parts of PetWay in PetLang. Freeze current codebase for bootstrapping.

Revise CharPtr. Merge with String? I.e. use str_static along with str_embedded? Think through UTF-8 type.

Think through objectives concept as an alternative to tracebacks.

Think through variadic arguments and results concept in PetLang.

Think through concept of multiple exit points. That's like promises that have two callbacks: resolve and reject.