#lang scribble/doc
@; THIS FILE IS GENERATED
@(require scribble/manual)
@(require (for-label (planet neil/shootout:1:0)))
@title[#:version "0.1"]{@bold{shootout}: Expression Performance Comparison for Racket}
@author{Neil Van Dyke}


License: @seclink["Legal" #:underline? #f]{LGPL 3} @(hspace 1) Web: @link["http://www.neilvandyke.org/racket-shootout/" #:underline? #f]{http://www.neilvandyke.org/racket-shootout/}

@defmodule[(planet neil/shootout:1:0)]

      

@section{Introduction}


      

This package provides the @tt{shootout} syntax, which is a convenient tool to help compare the performance of multiple Racket expressions.  This can be useful when hand-optimizing performance-sensitive Racket code.


      

For example, the program:


      

@SCHEMEBLOCK[
(define (va x (y "bbb") (z "ccc"))
  (expt 42 42)
  (string-append x y z))

(define (fa x y z)
  (expt 42 42)
  (string-append x y z))

(shootout (va "aaa")
          (fa "aaa" "bbb" "ccc")
          #:repeat 1000000)
]


      

might produce a log similar to:


      

@verbatim["SHOOTOUT-SAMPLING-GC-BASE\n\nSHOOTOUT-BEGIN (REPEAT 1000000, GC-BASE-MS 2498, GC-BASE-GCMS 2496)\n\nSHOOTOUT-EXPRESSION 1:\n(va \"aaa\")\nSHOOTOUT-TIMING (RUN 275, RUN-GCMS 12, COST 274, COST-GCMS 12, CLEANUP-DIFF -2.0)\n\nSHOOTOUT-EXPRESSION 2:\n(fa \"aaa\" \"bbb\" \"ccc\")\nSHOOTOUT-TIMING (RUN 255, RUN-GCMS 12, COST 254, COST-GCMS 13, CLEANUP-DIFF -1.0)\n\nSHOOTOUT-END"]


      

The most meaningful numbers in this version of @tt{shootout} are ``RUN'' and ``RUN-GCMS''.  RUN is the real time in milliseconds during which the expression ran for the specificed number of iteractions (the ``REPEAT'' number).  ``RUN-GMCS'' is the number of milliseconds of garbage collection (GC) time that occurred during the run.  Neither of these numbers includes the GC ``cleanup'' time that @tt{shootout} performs in an attempt to gauge any lingering GC cost of the expression.


      

Note that multiple runs of @tt{shootout} may give substantially different results.  So, you may wish to run multiple times and take the variation into consideration before drawing any conclusions.


      

Note that @tt{shootout} is only an aid for performance-comparison, and does not control for all variables, nor are its measurements necessarily accurate.


    
      

@section{Interface}


      

@defform[#:id shootout (shootout expr ... #:repeat repeat)]{
          

Performs @schemevarfont{repeat} iterations of each @schemevarfont{expr} and reports performance information in a log.


          

Note that the format of this log and the information is reports is likely to change in future versions of this package.


        }

    
      

@section{History}


      

@itemize[

@item{Version 0.1 --- 2010-12-21 -- PLaneT @tt{(1 0)}
            

Initial release.


          }



]


    

@section[#:tag "Legal"]{Legal}



Copyright (c) 2010 Neil Van Dyke.  This program is Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License (LGPL 3), or (at your option) any later version. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.  See http://www.gnu.org/licenses/ for details.  For other licenses and consulting, please contact the author.