Calling conventions

Interface methods and most wrapper functions return bool, where false indicates an error.

Historicaly unix way was around processes and the standard C library provides global variable errno as an explanation what exactly happened. With the rise of threads they had to make errno thread-local, but there's still nothing for the deeper async level.

PetWay is towards asynchronous features, but they are still at planning stage. For now PetWay defines current_task thread-local variable that contains the only value: status.

When an error is encountered, PetWay methods and functions should call pw_set_status and return false. Some wrappers, such as pw_get_fd, return values of interest directly if interface method never fail. Although they may panic if necessary interface is not implemented.

PwValues are passed by reference using PwValuePtr for declaring function arguments. When values are stored in local variables this does not cause any race conditions. Values stored in global variables or in dynamically allocated memory should be cloned for further processing. That's what pw_array_item and pw_map_get do when return items.

Result is also PwValuePtr which normally points to a local variable. The variable must be declared with PW_NULL initializer for pw_destroy to work properly. When a value is returned, this should be done either with pw_clone2 or pw_move.

C helpers

Generics

Generics is an amazing feature of modern C that make it convenient. They are heavily used in PetWay to interface with C

Generics allow to mimic overloaded functions, i.e.

pw_list_append(mylist, 1);
pw_list_append(mylist, "wow");

The downside of generics is ugly preprocessor output.

Wrappers for variadic functions

All variadic functions in PetWay except pw_register_interface are wrappers that add terminator to variadic arguments.

Usually terminator is -1, nullptr, or special PwVaEnd() status for PwValues passed by value.

Array and Map constructors

Macros pw_array_va(result, ...), pw_map_va(result, ...) and their companions that return result by value pwva_array(...) and pwva_map(...) simplify creation of arrays and maps in C code.

However, these macros treat arguments of status type as errors. If a status is encountered, it is used as return value.

On exit all arguments are destroyed. Extra care should be taken when passing local variables. Always use pw_clone() for this purpose.

Values returned by pwva_array(...) and pwva_map(...) should not be discarded to avoid memory leaks. The best way to handle them is assigning to a local variable so autocleaning would work.

Example:

PwValue map = pwva_map(&map,
    PwString("foo"), PwSigned(42),
    PwString("bar"), pwva_map(PwString("hello"), PwString("world"))
);