README.md in stackprof-0.1.0 vs README.md in stackprof-0.2.0

@@ -5,20 +5,21 @@
 inspired heavily by [gperftools](https://code.google.com/p/gperftools/),
 and written as a replacement for [perftools.rb](https://github.com/tmm1/perftools.rb)
 
 ### sampling
 
-three sampling modes are supported:
+four sampling modes are supported:
 
-  - cpu time (using `ITIMER_PROF` and `SIGPROF`)
-  - wall time (using `ITIMER_REAL` and `SIGALRM`)
-  - object allocation (using `RUBY_INTERNAL_EVENT_NEWOBJ`)
+  - :wall (using `ITIMER_REAL` and `SIGALRM`) [default mode]
+  - :cpu (using `ITIMER_PROF` and `SIGPROF`)
+  - :object (using `RUBY_INTERNAL_EVENT_NEWOBJ`)
+  - :custom (user-defined via `StackProf.sample`)
 
 samplers have a tuneable interval which can be used to reduce overhead or increase granularity:
 
-  - cpu time: sample every _interval_ microseconds of cpu activity (default: 10000 = 10 milliseconds)
-  - wall time: sample every _interval_ microseconds of wallclock time (default: 10000)
+  - wall time: sample every _interval_ microseconds of wallclock time (default: 1000)
+  - cpu time: sample every _interval_ microseconds of cpu activity (default: 1000 = 1 millisecond)
   - object allocation: sample every _interval_ allocations (default: 1)
 
 samples are taken using a combination of three new C-APIs in ruby 2.1:
 
   - signal handlers enqueue a sampling job using `rb_postponed_job_register_one`.
@@ -135,15 +136,16 @@
                          |    23  |     end
 ```
 
 ### usage
 
-the profiler is compiled as a C-extension and exposes a simple api: `StackProf.run(mode, interval)`.
+the profiler is compiled as a C-extension and exposes a simple api: `StackProf.run(mode: [:cpu|:wall|:object])`.
 the `run` method takes a block of code and returns a profile as a simple hash.
 
 ``` ruby
-profile = StackProf.run(sampling_mode, sampling_interval) do
+# sample after every 1ms of cpu activity
+profile = StackProf.run(mode: :cpu, interval: 1000) do
   MyCode.execute
 end
 ```
 
 this profile data structure is part of the public API, and is intended to be saved
@@ -152,14 +154,16 @@
 
 the format itself is very simple. it contains a header and a list of frames. each frame has a unique id and
 identifying information such as its name, file and line. the frame also contains sampling data, including per-line
 samples, and a list of relationships to other frames represented as weighted edges.
 
-```
+``` ruby
 {:version=>1.0,
- :mode=>"cpu(1000)",
+ :mode=>:cpu,
+ :inteval=>1000,
  :samples=>188,
+ :missed_samples=>0,
  :frames=>
   {70346498324780=>
     {:name=>"A#pow",
      :file=>"/Users/tmm1/code/stackprof/sample.rb",
      :line=>11,
@@ -182,16 +186,19 @@
 divided up between its callee edges. all 91 calls to `A#pow` came from `A#initialize`, as seen by the edge numbered
 `70346498324780`.
 
 ### advanced usage
 
-the profiler can be started, paused, resumed and stopped manually for greater control.
+the profiler can be started and stopped manually. results are accumulated until retrieval, across
+multiple start/stop invocations.
 
-```
+``` ruby
 StackProf.running?
 StackProf.start
-StackProf.pause
-StackProf.paused?
-StackProf.resume
 StackProf.stop
 StackProf.results
 ```
+
+### todo
+
+* file/iseq blacklist
+* restore signal handlers on stop