mirror-github-bspeice/qadapt
1
0
Fork 0
mirror of https://github.com/bspeice/qadapt synced 2024-11-21 21:38:10 -05:00
Code Issues Releases Wiki Activity

Update the docs

Browse Source
This commit is contained in:
Bradlee Speice 2018-11-10 21:36:23 -05:00
parent a7df1639ce
commit de7edaeb0c
2 changed files with 24 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
qadapt-macro/src/lib.rs
View File

@ -1,12 +1,8 @@
//! Helper macros to use with the QADAPT allocator system //! Helper macros to use with the QADAPT allocator system
//! //!
//! This crate is unusable on its own, but because `proc_macro` crates //! This crate is intended for managing the QADAPT allocator,
//! can't export non-proc-macro symbols, we have to go through an extra step //! and is unusable on its own.
//! to move these up.
//! //!
//! Ultimately, this does actually work because we don't need to actually use
//! references to the underlying functionality here, we just need to know
//! where they will ultimately end up at.
// TODO: This causes issues, but I can't track down why // TODO: This causes issues, but I can't track down why
// #![deny(missing_docs)] // #![deny(missing_docs)]
extern crate proc_macro; extern crate proc_macro;
@ -15,8 +11,11 @@ use proc_macro::TokenTree;
use proc_macro::TokenStream; use proc_macro::TokenStream;
/// Set up the QADAPT allocator to trigger a panic if any allocations happen during /// Set up the QADAPT allocator to trigger a panic if any allocations happen during
/// this function. Race conditions between threads are not checked, this macro will /// calls to this function.
/// only work as intended in a single-threaded or otherwise synchronized environment. ///
/// QADAPT will only track allocations in the thread that calls this function;
/// if (for example) this function receives the results of an allocation in a
/// separate thread, QADAPT will not trigger a panic.
#[proc_macro_attribute] #[proc_macro_attribute]
pub fn allocate_panic(_attr: TokenStream, item: TokenStream) -> TokenStream { pub fn allocate_panic(_attr: TokenStream, item: TokenStream) -> TokenStream {
let ret = item.clone(); let ret = item.clone();

17
src/lib.rs
View File

@ -1,3 +1,15 @@
//! The Quick And Dirty Allocation Profiling Tool
//!
//! This allocator is a helper for writing high-performance code that is allocation/drop free;
//! for functions annotated with `#[allocate_panic]`, QADAPT will detect when allocations/drops
//! happen during their execution (and execution of any functions they call) and throw a
//! thread panic if this occurs.
//!
//! Because QADAPT panics on allocation and is rather slow (for an allocator) it is **strongly**
//! recommended that QADAPT (the allocator) be used only in code tests. Functions annotated with
//! `#[allocate_panic]` will have no side effects if the QADAPT allocator is not being used,
//! so the attribute is safe to leave everywhere.
#![deny(missing_docs)]
extern crate libc; extern crate libc;
extern crate qadapt_macro; extern crate qadapt_macro;
extern crate spin; extern crate spin;
@ -18,8 +30,11 @@ thread_local! {
static PROTECTION_LEVEL: RwLock<u32> = RwLock::new(0); static PROTECTION_LEVEL: RwLock<u32> = RwLock::new(0);
} }
/// The QADAPT allocator itself
pub struct QADAPT; pub struct QADAPT;
/// Let QADAPT know that we are now entering a protected region and that
/// panics should be triggered if allocations/drops happen while we are running.
pub fn enter_protected() { pub fn enter_protected() {
if thread::panicking() { if thread::panicking() {
return return
@ -30,6 +45,8 @@ pub fn enter_protected() {
}).unwrap_or_else(|_e| ()); }).unwrap_or_else(|_e| ());
} }
/// Let QADAPT know that we are exiting a protected region. Will panic
/// if we attempt to [`exit_protected`] more times than we [`enter_protected`].
pub fn exit_protected() { pub fn exit_protected() {
if thread::panicking() { if thread::panicking() {
return return