Add readme and owners, improve comments

Finishing touches before the library is more or less ready to use.

Bug: 289989828
Test: atrace
Test: Manually collected trace
Change-Id: I0186bbff1417fefde8056a9e8e39055988d1875a

1 files changed, 26 insertions, 6 deletions

diff --git a/libatrace_rust/example/src/main.rs b/libatrace_rust/example/src/main.rs
index 80a2e919..84e3e470 100644
--- a/libatrace_rust/example/src/main.rs
+++ b/libatrace_rust/example/src/main.rs
@@ -19,18 +19,31 @@ use std::thread::JoinHandle;
 use atrace::AtraceTag;
 
 fn spawn_async_event() -> JoinHandle<()> {
-    atrace::atrace_async_begin(AtraceTag::App, "Async task", 12345);
-    std::thread::spawn(|| {
+    // Unlike normal events, async events don't need to be nested.
+    // You need to use the same name and cookie (the last arg) to close the event.
+    // The cookie must be unique on the name level.
+    let unique_cookie = 12345;
+    atrace::atrace_async_begin(AtraceTag::App, "Async task", unique_cookie);
+    std::thread::spawn(move || {
         std::thread::sleep(std::time::Duration::from_millis(500));
-        atrace::atrace_async_end(AtraceTag::App, "Async task", 12345);
+        atrace::atrace_async_end(AtraceTag::App, "Async task", unique_cookie);
     })
 }
 
 fn spawn_async_event_with_track() -> JoinHandle<()> {
-    atrace::atrace_async_for_track_begin(AtraceTag::App, "Async track", "Task with track", 12345);
-    std::thread::spawn(|| {
+    // Same as `atrace_async_begin` but per track.
+    // Track name (not event name) and cookie are used to close the event.
+    // The cookie must be unique on the track level.
+    let unique_cookie = 12345;
+    atrace::atrace_async_for_track_begin(
+        AtraceTag::App,
+        "Async track",
+        "Task with track",
+        unique_cookie,
+    );
+    std::thread::spawn(move || {
         std::thread::sleep(std::time::Duration::from_millis(600));
-        atrace::atrace_async_for_track_end(AtraceTag::App, "Async track", 12345);
+        atrace::atrace_async_for_track_end(AtraceTag::App, "Async track", unique_cookie);
     })
 }
 
@@ -38,16 +51,20 @@ fn spawn_counter_thread() -> JoinHandle<()> {
     std::thread::spawn(|| {
         for i in 1..=10 {
             std::thread::sleep(std::time::Duration::from_millis(100));
+            // Counter events are available for int and int64 to trace values.
             atrace::atrace_int(AtraceTag::App, "Count of i", i);
         }
     })
 }
 
 fn main() {
+    // This macro will create a scoped event with the function name used as the event name.
     atrace::trace_method!(AtraceTag::App);
 
+    // The scoped event will be ended when the returned guard is dropped.
     let _scoped_event = atrace::begin_scoped_event(AtraceTag::App, "Example main");
 
+    // Methods starting with atrace_* are direct wrappers of libcutils methods.
     let enabled_tags = atrace::atrace_get_enabled_tags();
     println!("Enabled tags: {:?}", enabled_tags);
 
@@ -56,9 +73,12 @@ fn main() {
     let async_event_with_track_handler = spawn_async_event_with_track();
     let counter_thread_handler = spawn_counter_thread();
 
+    // Instant events have no duration and don't need to be closed.
     atrace::atrace_instant(AtraceTag::App, "Instant event");
 
     println!("Calling atrace_begin and sleeping for 1 sec...");
+    // If you begin an event you need to close it with the same tag. If you're calling begin
+    // manually make sure you have a matching end. Or just use a scoped event.
     atrace::atrace_begin(AtraceTag::App, "Hello tracing!");
     std::thread::sleep(std::time::Duration::from_secs(1));
     atrace::atrace_end(AtraceTag::App);