diff --git a/_03.Standard-library.sz b/_03.Standard-library.sz index 6ed7387..be81ded 100644 --- a/_03.Standard-library.sz +++ b/_03.Standard-library.sz @@ -47,7 +47,7 @@ For more details, see @link["modules/std/atomic.html"]{@code{(std atomic)}}. @subsection{std/stm} Software transactional memory, after the OCaml library kcas. A @code{(Loc T)} holds one value, and a transaction is a function of a @code{Tx} that reads and writes locations with @code{tx-ref}, @code{tx-set!}, @code{tx-update!} and @code{tx-swap!}. @code{atomically} runs it and commits all of its writes as one step, and runs it again if another transaction changed what it read. @code{tx-retry} stops a transaction until a location that it read changes, and @code{atomically-evt} is the transaction as a CML event, so waiting for a condition combines with timeouts, channels and cancellation in a @code{choose}. @code{tx-or-else} tries alternatives. Three modules build data structures out of locations: @code{(std stm queue)} has the FIFO queue @code{TQueue}, with the channel names @code{queue-send}, @code{queue-recv}, @code{queue-put} and @code{queue-get} outside a transaction; @code{(std stm map)} has the hash map @code{TMap}, whose operations are named as those of the prelude's @code{Map}; and @code{(std stm counter)} has @code{TCounter}, a number that fibers on different CPUs add to without conflicts. Part II has a guide in the section on concurrency. -For more details, see @link["modules/std/stm.html"]{@code{(std stm)}}, @link["modules/std/stm/queue.html"]{@code{(std stm queue)}}, @link["modules/std/stm/map.html"]{@code{(std stm map)}} and @link["modules/std/stm/counter.html"]{@code{(std stm counter)}}. +For more details, see @link["modules/std/stm/"]{@code{(std stm)}}, @link["modules/std/stm/queue.html"]{@code{(std stm queue)}}, @link["modules/std/stm/map.html"]{@code{(std stm map)}} and @link["modules/std/stm/counter.html"]{@code{(std stm counter)}}. @subsection{std/datetime} @@ -92,7 +92,10 @@ For more details, see @link["modules/std/ports.html"]{@code{(std ports)}} and @l @subsection{std/test and std/simpletest} @code{(std test)} has tests that are silent unless they fail. @code{deftest} registers a test, @code{check} reports the values that it saw when it fails, and @code{(run-tests)} is the @code{main} of the file. Each test runs in a scope with a deadline. The test fails if it leaves a resource open, and the scope waits for the fibers that the test started. @code{bjo test} builds and runs the test files of a project. @code{(std simpletest)} is the older harness: an assertion prints one line, and a failure prints a line that starts with @code{FAILURE:}. Its @code{with-fake-fs}, a filesystem in memory, also works inside a @code{deftest}. -For more details, see @link["modules/std/test.html"]{@code{(std test)}} and @link["modules/std/simpletest.html"]{@code{(std simpletest)}}. + +@code{(std test prop)} has property tests. @code{for-all} runs its body many times with generated values. When a run fails, @code{for-all} shrinks it to a small case, reports that case, and stores it beside the test file, so the next run tries it first. @code{assume} discards a run, @code{label} names the failures in its body, and @code{classify} and @code{collect} count the runs for @code{--stats}. @code{(std test gen)} has the generators, and @code{Arbitrary}, which gives the default generator of a type. @code{(std test expect)} has @code{expect-output}, which compares the output of a body with a text in the test, and @code{--promote} updates that text. + +For more details, see @link["modules/std/test/"]{@code{(std test)}}, @link["modules/std/test/prop.html"]{@code{(std test prop)}}, @link["modules/std/test/gen.html"]{@code{(std test gen)}}, @link["modules/std/test/expect.html"]{@code{(std test expect)}} and @link["modules/std/simpletest.html"]{@code{(std simpletest)}}. @subsection{std/stopwatch} diff --git a/modules/std/stm.sz b/modules/std/stm.sz deleted file mode 100644 index 8173d54..0000000 --- a/modules/std/stm.sz +++ /dev/null @@ -1,3 +0,0 @@ -(meta (title "(std stm)")) - -@generate-docs[#:module "std stm"] diff --git a/modules/std/stm/index.sz b/modules/std/stm/index.sz index 5742930..6fe8eaf 100644 --- a/modules/std/stm/index.sz +++ b/modules/std/stm/index.sz @@ -1,2 +1,11 @@ -(meta (title "std stm: transactional data structures") +(meta (title "(std stm)") (sort title)) + +@strong{Submodules:} +@itemlist{ + @item{@link["map.html"]{@code{(std stm map)}}: a transactional hash map, @code{TMap}.} + @item{@link["queue.html"]{@code{(std stm queue)}}: a transactional FIFO queue, @code{TQueue}, that is also a CML event.} + @item{@link["counter.html"]{@code{(std stm counter)}}: a striped counter, @code{TCounter}, with few write conflicts between cores.} +} + +@generate-docs[#:module "std stm"] diff --git a/modules/std/test.sz b/modules/std/test.sz deleted file mode 100644 index 367106c..0000000 --- a/modules/std/test.sz +++ /dev/null @@ -1,3 +0,0 @@ -(meta (title "(std test)")) - -@generate-docs[#:module "std test"] diff --git a/modules/std/test/expect.sz b/modules/std/test/expect.sz new file mode 100644 index 0000000..36a21b8 --- /dev/null +++ b/modules/std/test/expect.sz @@ -0,0 +1,3 @@ +(meta (title "(std test expect)")) + +@generate-docs[#:module "std test expect"] diff --git a/modules/std/test/gen.sz b/modules/std/test/gen.sz new file mode 100644 index 0000000..0a825b8 --- /dev/null +++ b/modules/std/test/gen.sz @@ -0,0 +1,3 @@ +(meta (title "(std test gen)")) + +@generate-docs[#:module "std test gen"] diff --git a/modules/std/test/index.sz b/modules/std/test/index.sz new file mode 100644 index 0000000..f3de973 --- /dev/null +++ b/modules/std/test/index.sz @@ -0,0 +1,11 @@ +(meta (title "(std test)") + (sort title)) + +@strong{Submodules:} +@itemlist{ + @item{@link["prop.html"]{@code{(std test prop)}}: property tests with @code{for-all}.} + @item{@link["gen.html"]{@code{(std test gen)}}: the generators that @code{for-all} draws from, and @code{Arbitrary}.} + @item{@link["expect.html"]{@code{(std test expect)}}: tests that compare output with a text in the test.} +} + +@generate-docs[#:module "std test"] diff --git a/modules/std/test/prop.sz b/modules/std/test/prop.sz new file mode 100644 index 0000000..0dea817 --- /dev/null +++ b/modules/std/test/prop.sz @@ -0,0 +1,3 @@ +(meta (title "(std test prop)")) + +@generate-docs[#:module "std test prop"]