Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sunfishcode/atomic-dbg
Atomic `dbg`/`eprintln`/`eprint` macros
https://github.com/sunfishcode/atomic-dbg
Last synced: 5 days ago
JSON representation
Atomic `dbg`/`eprintln`/`eprint` macros
- Host: GitHub
- URL: https://github.com/sunfishcode/atomic-dbg
- Owner: sunfishcode
- License: other
- Created: 2022-05-04T22:57:55.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-09T02:00:07.000Z (9 months ago)
- Last Synced: 2024-11-01T12:52:23.138Z (12 days ago)
- Language: Rust
- Size: 22.5 KB
- Stars: 17
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# atomic-dbg
This crate provides [`dbg`], [`eprint`], and [`eprintln`], macros which work
just like their [counterparts] [in] [std], but which:
- Write atomically, up to the greatest length supported on the platform.
- Don't use locks (in userspace) or dynamic allocations.
- Preserve libc's `errno` and Windows' last-error code value.
This means they can be used just about anywhere within a program, including
inside allocator implementations, inside synchronization primitives, startup
code, around FFI calls, inside signal handlers, and in the child process of a
`fork` before an `exec`.
And, when multiple threads are printing, as long as they're within the length
supported on the platform, the output is readable instead of potentially
interleaved with other output.
For example, this code:
```rust
use atomic_dbg::dbg;
fn main() {
dbg!(2, 3, 4);
}
```
Has this strace output:
```notrust
write(2, "[examples/dbg.rs:4] 2 = 2\n[examples/dbg.rs:4] 3 = 3\n[examples/dbg.rs:4] 4 = 4\n", 78[examples/dbg.rs:4] 2 = 2
```
which is a single atomic `write` call.
For comparison, with `std::dbg` it looks like this:
```notrust
write(2, "[", 1[) = 1
write(2, "examples/dbg.rs", 15examples/dbg.rs) = 15
write(2, ":", 1:) = 1
write(2, "4", 14) = 1
write(2, "] ", 2] ) = 2
write(2, "2", 12) = 1
write(2, " = ", 3 = ) = 3
write(2, "2", 12) = 1
write(2, "\n", 1
) = 1
write(2, "[", 1[) = 1
write(2, "examples/dbg.rs", 15examples/dbg.rs) = 15
write(2, ":", 1:) = 1
write(2, "4", 14) = 1
write(2, "] ", 2] ) = 2
write(2, "3", 13) = 1
write(2, " = ", 3 = ) = 3
write(2, "3", 13) = 1
write(2, "\n", 1
) = 1
write(2, "[", 1[) = 1
write(2, "examples/dbg.rs", 15examples/dbg.rs) = 15
write(2, ":", 1:) = 1
write(2, "4", 14) = 1
write(2, "] ", 2] ) = 2
write(2, "4", 14) = 1
write(2, " = ", 3 = ) = 3
write(2, "4", 14) = 1
write(2, "\n", 1
) = 1
```
atomic-dbg is `no_std`, however like `std`, it uses the stderr file descriptor
ambiently, assuming that it's open.
## Logging
With the "log" feature enabled, atomic-dbg defines an `atomic_dbg::log::init`
which installed a minimal logging implementation using the `eprintln` macro.
[counterparts]: https://doc.rust-lang.org/stable/std/macro.dbg.html
[in]: https://doc.rust-lang.org/stable/std/macro.eprintln.html
[std]: https://doc.rust-lang.org/stable/std/macro.eprint.html
[`dbg`]: https://docs.rs/atomic-dbg/latest/atomic-dbg/macro.dbg.html
[`eprintln`]: https://docs.rs/atomic-dbg/latest/atomic-dbg/macro.eprintln.html
[`eprint`]: https://docs.rs/atomic-dbg/latest/atomic-dbg/macro.eprint.html