libk  Check-in [c8e83b4bdf]

Overview
Comment:clarify error-handling
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: c8e83b4bdfb3787d23509b7c9dfebc5e03509e471790ef2944e90259c1bed0d5
User & Date: lexi on 2019-08-26 20:02:46
Other Links: manifest | tags
Context
2019-08-26
20:03
fix typo check-in: 9ea8c28897 user: lexi tags: trunk
20:02
clarify error-handling check-in: c8e83b4bdf user: lexi tags: trunk
19:58
fix typo check-in: 112ee76a31 user: lexi tags: trunk
Changes

Modified libk.md from [20f3e7f305] to [abadd8c1b0].

210
211
212
213
214
215
216
217
218
219
220

221
222
223
224
225
226
227
	};

this makes code much more legible and has the added benefit of making the definitions easier to expand at a later date if new functionality is needed without breaking the API or ABI.

## error handling
every module has a `cond` type (e.g. `kscond` for `kstr` or `kconf_cond` for `kconf`). this is an enumeration type that represents every possible error a module can return, and every `cond` type obeys a number of invariants (in addition to the usual namespacing rules:

1. every member of a cond type has a globally unique integer value. this means that `kscond_ok` has an integer value is not equal to `kmcond_ok`.
2. every member of a cond type has a member `kmcond_ok` which represents success. this member's integer value is always an exact multiple of the "module offset", the number of condition values allocated to each module (currently `0x7F`).
3. the `kokay()` function, defined in `kcore`, when called on a member of a `cond` type will return true if that member represents total success and false otherwise.
4. every cond type has a value `*cond_fail`, for instance `kconf_cond_fail`. if a condition is greater than or equal to its module's `fail` value, it represents a total failure. if it is lesser than the fail value, it represents either success, partial success, or some other condition that does not equate to total failure.


the reason each error value is unique is that this allows us to map every single condition code unambiguously to an error message. a forthcoming `kcore` function will do exactly that and produce an error string that can be displayed to a user or for debugging purposes. another useful property is that each integer value has at most only one possible meaning in the context of error codes, allowing for centralized error handling - a `kscond` and a `kmcond` can both be turned into an `int` without loss of information, and e.g. `kscond_fail` != `kmcond_fail` != `kconf_cond_fail`.

this is particularly useful as C does not have exceptions, and thus the only viable error-handling mechanisms are early-exit and early-return; any `cond` value can be propagated up the function stack without losing its unique meaning.

the value of each condition code is determined at compile time.
 







|
|


>







210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
	};

this makes code much more legible and has the added benefit of making the definitions easier to expand at a later date if new functionality is needed without breaking the API or ABI.

## error handling
every module has a `cond` type (e.g. `kscond` for `kstr` or `kconf_cond` for `kconf`). this is an enumeration type that represents every possible error a module can return, and every `cond` type obeys a number of invariants (in addition to the usual namespacing rules:

1. every member of a `cond` type has an integer value that is unique among all modules' `cond` types. for instance, this means that `kscond_ok` has an integer value that is not equal to `kmcond_ok`.
2. every member of a cond type has a member `kmcond_ok` which represents total success. this member's integer value is always an exact multiple of the "module offset", the number of condition values allocated to each module (currently `0x7F`).
3. the `kokay()` function, defined in `kcore`, when called on a member of a `cond` type will return true if that member represents total success and false otherwise.
4. every cond type has a value `*cond_fail`, for instance `kconf_cond_fail`. if a condition is greater than or equal to its module's `fail` value, it represents a total failure. if it is lesser than the fail value, it represents either success, partial success, or some other condition that does not equate to total failure.
5. if a `cond` value is greater than its module's `*cond_ok` value but less than the `*cond_fail` value, it represents a condition that is neither total success nor total failure; for instance, a partial write, or an attempt to free memory that does not need to be freed.

the reason each error value is unique is that this allows us to map every single condition code unambiguously to an error message. a forthcoming `kcore` function will do exactly that and produce an error string that can be displayed to a user or for debugging purposes. another useful property is that each integer value has at most only one possible meaning in the context of error codes, allowing for centralized error handling - a `kscond` and a `kmcond` can both be turned into an `int` without loss of information, and e.g. `kscond_fail` != `kmcond_fail` != `kconf_cond_fail`.

this is particularly useful as C does not have exceptions, and thus the only viable error-handling mechanisms are early-exit and early-return; any `cond` value can be propagated up the function stack without losing its unique meaning.

the value of each condition code is determined at compile time.