suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

- updated the descriptions of statistics and related functions to

Browse Source 
reflect the Version 9.3.1 change from sstats structures to sstats
  records, with sstats times represented as time objects and sstats
  bytes and counts represented as exact integers; also updated the
  sstats-difference description to reflect that it no longer coerces
  negative differences to zero.  added a corresponding release note.
    system.stex,
    release_notes.stex

original commit: cd93f130c2a911d67bc19b75da0f205d50b8f6ff
This commit is contained in:
dybvig 2016-06-09 00:11:45 -04:00
parent b2891bc519
commit 8935c6fbd9
3 changed files with 48 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
LOG
View File

@ -178,3 +178,11 @@
newrelease, LOG newrelease, LOG
- replaced a couple of tabs - replaced a couple of tabs
number.c number.c
- updated the descriptions of statistics and related functions to
reflect the Version 9.3.1 change from sstats structures to sstats
records, with sstats times represented as time objects and sstats
bytes and counts represented as exact integers; also updated the
sstats-difference description to reflect that it no longer coerces
negative differences to zero. added a corresponding release note.
system.stex,
release_notes.stex

88
csug/system.stex
View File

@ -3856,7 +3856,7 @@ integer less than $10^9$.
\schemedisplay \schemedisplay
(time-type (current-time)) ;=> time-utc (time-type (current-time)) ;=> time-utc
(time-type (current-time 'time-process)) ;=> time-process (time-type (current-time 'time-process)) ;=> time-process
(time-type (make-time 'time-duration 0 50) ;=> time-duration (time-type (make-time 'time-duration 0 50)) ;=> time-duration
(time-second (current-time)) ;=> 1198816497 (time-second (current-time)) ;=> 1198816497
(time-nanosecond (current-time)) ;=> 2399000 (time-nanosecond (current-time)) ;=> 2399000
(time-second (make-time 'time-duration 10 -5)) ;=> -5 (time-second (make-time 'time-duration 10 -5)) ;=> -5
@ -4318,14 +4318,14 @@ of the heap to the current size of the heap.
%---------------------------------------------------------------------------- %----------------------------------------------------------------------------
\entryheader \entryheader
\formdef{statistics}{\categoryprocedure}{(statistics)} \formdef{statistics}{\categoryprocedure}{(statistics)}
\returns a sstats structure containing current statistics \returns a sstats record containing current statistics
\listlibraries \listlibraries
\endentryheader \endentryheader
\noindent \noindent
\scheme{statistics} packages together various timing and allocation \scheme{statistics} packages together various timing and allocation
statistics into a single \scheme{sstats} structure. statistics into a single \scheme{sstats} record.
A \scheme{sstats} structure has the following fields: A \scheme{sstats} record has the following fields:
\begin{description} \begin{description}
\item[\scheme{cpu},] the cpu time consumed, \item[\scheme{cpu},] the cpu time consumed,
@ -4339,53 +4339,40 @@ A \scheme{sstats} structure has the following fields:
\noindent \noindent
All values are computed since system start-up. All values are computed since system start-up.
All times are calculated in milliseconds. The time values are time objects (Section~\ref{SECTSYSTEMTIMESNDATES}),
and the bytes and count values are exact integers.
The \scheme{sstats} structure and the corresponding allocation procedure,
predicate, accessors, and setters described below are defined as vector-based
structures as if via \scheme{define-structure}
(Section~\ref{SECTCOMPATSTRUCTURES}) as follows.
\schemedisplay
(define-structure
(sstats cpu real bytes
gc-count gc-cpu gc-real gc-bytes))
\endschemedisplay
\scheme{statistics} might be defined as follows: \scheme{statistics} might be defined as follows:
\schemedisplay \schemedisplay
(define statistics (define statistics
(lambda () (lambda ()
(define millis
(lambda (t)
(+ (* (time-second t) 1000)
(quotient (time-nanosecond t) 1000000))))
(make-sstats (make-sstats
(cpu-time) (current-time 'time-thread)
(real-time) (current-time 'time-monotonic)
(- (+ (bytes-allocated) (bytes-deallocated)) (- (+ (bytes-allocated) (bytes-deallocated))
(initial-bytes-allocated)) (initial-bytes-allocated))
(collections) (collections)
(millis (current-time 'time-collector-cpu)) (current-time 'time-collector-cpu)
(millis (current-time 'time-collector-real)) (current-time 'time-collector-real)
(bytes-deallocated)))) (bytes-deallocated))))
\endschemedisplay \endschemedisplay
%---------------------------------------------------------------------------- %----------------------------------------------------------------------------
\entryheader \entryheader
\formdef{make-sstats}{\categoryprocedure}{(make-sstats \var{cpu} \var{real} \var{bytes} \var{gc-count} \var{gc-cpu} \var{gc-real} \var{gc-bytes})} \formdef{make-sstats}{\categoryprocedure}{(make-sstats \var{cpu} \var{real} \var{bytes} \var{gc-count} \var{gc-cpu} \var{gc-real} \var{gc-bytes})}
\returns a sstats structure \returns a sstats record
\listlibraries \listlibraries
\endentryheader \endentryheader
Each of the arguments must be a real number. The time arguments (\var{cpu}, \var{real}, \var{gc-cpu}, and \var{gc-real}) must be time objects.
The other arguments must be exact integers.
%---------------------------------------------------------------------------- %----------------------------------------------------------------------------
\entryheader \entryheader
\formdef{sstats?}{\categoryprocedure}{(sstats? \var{obj})} \formdef{sstats?}{\categoryprocedure}{(sstats? \var{obj})}
\returns \scheme{#t} if \var{obj} is a sstats structure, otherwise \scheme{#f} \returns \scheme{#t} if \var{obj} is a sstats record, otherwise \scheme{#f}
\listlibraries \listlibraries
\endentryheader \endentryheader
@ -4404,51 +4391,42 @@ Each of the arguments must be a real number.
\endentryheader \endentryheader
\noindent \noindent
\var{s} must be a sstats structure. \var{s} must be a sstats record.
%---------------------------------------------------------------------------- %----------------------------------------------------------------------------
\entryheader \entryheader
\formdef{set-sstats-cpu!}{\categoryprocedure}{(set-sstats-cpu! \var{s} \var{obj})} \formdef{set-sstats-cpu!}{\categoryprocedure}{(set-sstats-cpu! \var{s} \var{new-value})}
\formdef{set-sstats-real!}{\categoryprocedure}{(set-sstats-real! \var{s} \var{obj})} \formdef{set-sstats-real!}{\categoryprocedure}{(set-sstats-real! \var{s} \var{new-value})}
\formdef{set-sstats-bytes!}{\categoryprocedure}{(set-sstats-bytes! \var{s} \var{obj})} \formdef{set-sstats-bytes!}{\categoryprocedure}{(set-sstats-bytes! \var{s} \var{new-value})}
\formdef{set-sstats-gc-count!}{\categoryprocedure}{(set-sstats-gc-count! \var{s} \var{obj})} \formdef{set-sstats-gc-count!}{\categoryprocedure}{(set-sstats-gc-count! \var{s} \var{new-value})}
\formdef{set-sstats-gc-cpu!}{\categoryprocedure}{(set-sstats-gc-cpu! \var{s} \var{obj})} \formdef{set-sstats-gc-cpu!}{\categoryprocedure}{(set-sstats-gc-cpu! \var{s} \var{new-value})}
\formdef{set-sstats-gc-real!}{\categoryprocedure}{(set-sstats-gc-real! \var{s} \var{obj})} \formdef{set-sstats-gc-real!}{\categoryprocedure}{(set-sstats-gc-real! \var{s} \var{new-value})}
\formdef{set-sstats-gc-bytes!}{\categoryprocedure}{(set-sstats-gc-bytes! \var{s} \var{obj})} \formdef{set-sstats-gc-bytes!}{\categoryprocedure}{(set-sstats-gc-bytes! \var{s} \var{new-value})}
\returns unspecified \returns unspecified
\listlibraries \listlibraries
\endentryheader \endentryheader
\noindent \noindent
\var{s} must be a sstats structure. \var{s} must be a sstats record, the \var{new-value} arguments for the time fields
Each procedure sets the value of the corresponding field (\var{cpu}, \var{real}, \var{gc-cpu}, and \var{gc-real})
to \var{obj}. must be time objects, and
the other \var{new-value} arguments must be exact integers.
Each procedure sets the value of the corresponding field of \var{s} to
\var{new-value}.
%---------------------------------------------------------------------------- %----------------------------------------------------------------------------
\entryheader \entryheader
\formdef{sstats-difference}{\categoryprocedure}{(sstats-difference \var{s_1} \var{s_2})} \formdef{sstats-difference}{\categoryprocedure}{(sstats-difference \var{s_1} \var{s_2})}
\returns a sstats structure representing the difference between \var{s_1} and \var{s_2} \returns a sstats record representing the difference between \var{s_1} and \var{s_2}
\listlibraries \listlibraries
\endentryheader \endentryheader
\noindent \noindent
\var{s_1} and \var{s_2} must be \scheme{sstats} structures. \var{s_1} and \var{s_2} must be sstats records.
\scheme{sstats-difference} subtracts each field of \var{s_2} from the \scheme{sstats-difference} subtracts each field of \var{s_2} from the
corresponding field of \var{s_1} to produce the result \scheme{sstats} corresponding field of \var{s_1} to produce the resulting \scheme{sstats}
structure. record.
It coerces negative results to zero.
\scheme{sstats-difference} is commonly used to measure the time elapsed
between two points in the execution of a program.
In doing such comparisons, it is often useful to adjust for overhead
in the statistics gathering functions by calling \scheme{statistics}
twice before timing a computation and once after; the difference in the
results of the first two calls is then subtracted from the difference in
the results of the last two calls.
After adjusting for overhead, small negative results could occur for very
fast running computations without the coercion of negative results to
zero by \scheme{sstats-difference}.
%---------------------------------------------------------------------------- %----------------------------------------------------------------------------
\entryheader \entryheader
@ -4459,7 +4437,7 @@ zero by \scheme{sstats-difference}.
\endentryheader \endentryheader
\noindent \noindent
\var{s} must be a \scheme{sstats} structure. \var{s} must be a \scheme{sstats} record.
If \var{textual-output-port} is not supplied, it defaults to the current output port. If \var{textual-output-port} is not supplied, it defaults to the current output port.
\scheme{sstats-print} displays the fields of \scheme{s} in a manner similar \scheme{sstats-print} displays the fields of \scheme{s} in a manner similar
to \scheme{display-statistics} and \scheme{time}. to \scheme{display-statistics} and \scheme{time}.

7
release_notes/release_notes.stex
View File

@ -109,6 +109,13 @@ maximum-generation collection.
It can be set to a lower generation number to cause the collector to It can be set to a lower generation number to cause the collector to
do so for younger generations we well. do so for younger generations we well.
\subsection{sstats changes (9.3.1)}
The vector-based sstats structure has been replaced with a record type.
The time fields are all time objects, and the bytes and count fields
are now exact integers.
\scheme{time-difference} no longer coerces negative results to zero.
\subsection{\protect\scheme{library-group} eliminated (9.3.1)} \subsection{\protect\scheme{library-group} eliminated (9.3.1)}
With the extensions to \scheme{compile-whole-program} and the With the extensions to \scheme{compile-whole-program} and the