63 lines
2.7 KiB
Racket
63 lines
2.7 KiB
Racket
#lang scribble/doc
|
|
|
|
@(require scribble/manual
|
|
(for-label scheme profile/sampler profile/analyzer))
|
|
|
|
@title[#:tag "sampler"]{Collecting Profile Information}
|
|
|
|
@defmodule[profile/sampler]
|
|
|
|
@defproc[(create-sampler [to-track (or/c thread? custodian?
|
|
(listof (or/c thread? custodian?)))]
|
|
[delay nonnegative-number?]
|
|
[super-cust custodian? (current-custodian)])
|
|
((symbol?) (any/c) . ->* . any/c)]{
|
|
|
|
Creates a sample collector thread, which tracks the given
|
|
@scheme[to-track] value every @scheme[delay] seconds. The
|
|
@scheme[to-track] value can be either a thread (track just that
|
|
thread), a custodian (track all threads managed by the custodian), or
|
|
a list of threads and/or custodians. If a custodian is given, it must
|
|
be subordinate to @scheme[super-cust], which defaults to the current
|
|
custodian.
|
|
|
|
The resulting value is a controller function, which consumes a message
|
|
consisting of a symbol and an optional argument, and can affect the
|
|
sampler. The following messages are currently supported:
|
|
@itemize[
|
|
|
|
@item{@scheme['pause] and @scheme['resume] will stop or resume data
|
|
collection. These messages can be nested. Note that the thread will
|
|
continue running it will just stop collecting snapshots.}
|
|
|
|
@item{@scheme['stop] kills the controlled thread. It should be called
|
|
when no additional data should be collected. (This is currently
|
|
irreversible: there is no message to start a new sampler thread.)}
|
|
|
|
@item{@scheme['set-tracked!] with a value will change the tracked
|
|
objects (initially specified as the @scheme[to-track] argument) to
|
|
the given value.}
|
|
|
|
@item{@scheme['set-tracked!] with a value will change the delay that
|
|
the sampler us taking between snapshots. Note that although
|
|
changing this means that the snapshots are not uniformly
|
|
distributed, the results will still be sensible --- this is because
|
|
the cpu time between samples is taken into account when the
|
|
resulting data is analyzed.}
|
|
|
|
@item{Finally, a @scheme['get-snapshots] message will make the
|
|
controller return the currently collected data. Note that this can
|
|
be called multiple times, each call will return the data thatis
|
|
collected up to that point in time. In addition, it can be (and
|
|
usually is) called after the sampler was stopped.
|
|
|
|
The value that is returned should be considered as an undocumented
|
|
internal detail of the profiler, to be sent to
|
|
@scheme[analyze-samples] for analysis. The reason this is not done
|
|
automatically, is that a future extension might allow you to combine
|
|
several sampler results, making it possible to combine a profile
|
|
analysis from several individual runs, possibly from different
|
|
machines.}
|
|
|
|
]}
|