From f9023b256b872e2f502f46bd2c40ef9b14950881 Mon Sep 17 00:00:00 2001
From: Matthew Butterick <mb@mbtype.com>
Date: Sat, 22 Nov 2014 19:55:23 -0800
Subject: [PATCH] add cache docs

---
 scribblings/cache.scrbl | 31 +++++++++++++++++++++++++++++++
 scribblings/sugar.scrbl |  2 ++
 2 files changed, 33 insertions(+)
 create mode 100644 scribblings/cache.scrbl

diff --git a/scribblings/cache.scrbl b/scribblings/cache.scrbl
new file mode 100644
index 0000000..aad6862
--- /dev/null
+++ b/scribblings/cache.scrbl
@@ -0,0 +1,31 @@
+#lang scribble/manual
+
+@(require scribble/eval (for-label racket sugar))
+
+@(define my-eval (make-base-eval))
+@(my-eval `(require sugar))
+
+@title{Cache}
+@defmodule[sugar/cache]
+
+If, like Ricky Bobby and me, you want to go fast, then try using more caches. They're wicked fast.
+
+@defproc[
+(make-caching-proc
+[proc procedure?])
+procedure?]
+Make a caching version of @racket[_proc]. This means a hash table will be attached to @racket[_proc], and result values will automatically be saved & retrieved. The arguments to the procedure are used as the hash key.
+
+In the example below, notice that both invocations of @racketfont{slow-op} take approximately the same time, whereas the second invocation of @racketfont{fast-op} uses the cache instead and thus is nearly instantaneous.
+
+@examples[#:eval my-eval
+(define (slow-op x) (for/sum ([i (in-range 100000000)]) i))
+(time (slow-op 42))
+(time (slow-op 42))
+(define fast-op (make-caching-proc slow-op))
+(time (fast-op 42))
+(time (fast-op 42))
+]
+
+@defform[(define/caching (name arg ... . rest-arg) body ...)]
+Like @racket[define], but automatically uses @racket[make-caching-proc] to define a caching version of the function.
diff --git a/scribblings/sugar.scrbl b/scribblings/sugar.scrbl
index facaa5e..a2dd5b3 100644
--- a/scribblings/sugar.scrbl
+++ b/scribblings/sugar.scrbl
@@ -18,6 +18,8 @@ A collection of small functions to help make Racket code simpler & more readable
 
 @include-section["installation.scrbl"]
 
+@include-section["cache.scrbl"]
+
 @include-section["coerce.scrbl"]
 
 @include-section["container.scrbl"]