diff options
author | Homu <homu@barosl.com> | 2016-02-28 22:53:05 +0900 |
---|---|---|
committer | Homu <homu@barosl.com> | 2016-02-28 22:53:05 +0900 |
commit | da2cb87849e00a7e2413c4103a4f86529fb6e58e (patch) | |
tree | b0e14d44213e46bd7982c0da667adf5d4f9a4f8b | |
parent | 6a2c1646d432e7803f4863250f176d847cf0a423 (diff) | |
parent | 4c5861c44ea2686da86bebd98eb7d303c9d66dd8 (diff) | |
download | nix-da2cb87849e00a7e2413c4103a4f86529fb6e58e.zip |
Auto merge of #282 - fiveop:CONVENTIONS, r=@kamalmarhubi
Add introduction/constants/enumeration/uninitialized to CONVENTIONS.
I have added new sections to the file. I would like the usual suspects to read them critically and offer critique.
When have agreed to add certain versions I will add Issues to track our progress in getting the code to follow the conventions. For two of the sections they already exist in #254 and #264.
-rw-r--r-- | CONVENTIONS.md | 45 | ||||
-rw-r--r-- | README.md | 4 |
2 files changed, 45 insertions, 4 deletions
diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 018a0437..4e4a4ab2 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -1,7 +1,44 @@ -# Bitflags +# Conventions + +In order to achieve our goal of wrapping [libc][libc] code in idiomatic rust +constructs with minimal performance overhead, we follow the following +conventions. + +Note that, thus far, not all the code follows these conventions and not all +conventions we try to follow have been documented here. If you find an instance +of either, feel free to remedy the flaw by opening a pull request with +appropriate changes or additions. + + +## Integer Constants + +We do not define integer constants ourselves, but use or reexport them from the +[libc crate][libc]. + + +## Bitflags We represent sets of constants that are intended to be combined using bitwise operations as parameters to functions by types defined using the `bitflags!` -macro from the [bitflags crate](https://crates.io/crates/bitflags/). -Instead of providing the concrete values ourselves, we prefer taking the -constants defined in [libc crate](https://crates.io/crates/libc/). +macro from the [bitflags crate][bitflags]. + + +## Enumerations + +We represent sets of constants that are intended as mutually exclusive arguments +to parameters of functions by [enumerations][enum]. + + +## Structures Initialized by libc Functions + +Whenever we need to use a [libc][libc] function to properly initialize a +variable and said function allows us to use uninitialized memory, we use +[`std::mem::uninitialized`][std_uninitialized] (or [`core::mem::uninitialized`][core_uninitialized]) +when defining the variable. This allows us to avoid the overhead incurred by +zeroing or otherwise initializing the variable. + +[bitflags]: https://crates.io/crates/bitflags/ +[core_uninitialized]: https://doc.rust-lang.org/core/mem/fn.uninitialized.html +[enum]: https://doc.rust-lang.org/reference.html#enumerations +[libc]: https://crates.io/crates/libc/ +[std_uninitialized]: https://doc.rust-lang.org/std/mem/fn.uninitialized.html @@ -28,3 +28,7 @@ Then, add this to your crate root: ```rust extern crate nix; ``` + +## Contributing + +See [CONTRIBUTING](CONTRIBUTING.md). |