Fix #116

README.Rmd

@@ -254,7 +254,7 @@ Please tune these these arguments to achieve the desired balance for auto-scalin
 
 # Risks
 
-The `crew` package has unavoidable risk. It is your responsibility as the user to safely use `crew`. Please read the final clause of the [software license](https://wlandau.github.io/crew/LICENSE.html).
+The `crew` package has unavoidable risk. It is your responsibility as the user to safely use `crew`. Please read the [software license](https://wlandau.github.io/crew/LICENSE.html) and the sub-sections below about specific known risks.
 
 ## Security
 

README.md

@@ -132,11 +132,11 @@ controller$pop() # No workers started yet and the task is not done.
 
 task <- controller$pop() # Worker started, task complete.
 task
-#> # A tibble: 1 × 11
-#>   name    command result seconds   seed error trace warnings launcher worker
-#>   <chr>   <chr>   <list>   <dbl>  <int> <chr> <chr> <chr>    <chr>     <int>
-#> 1 get pid NA      <int>        0 1.78e9 NA    NA    NA       372d50b…      1
-#> # ℹ 1 more variable: instance <chr>
+#> # A tibble: 1 × 12
+#>   name    command result seconds  seed algorithm error trace warnings
+#>   <chr>   <chr>   <list>   <dbl> <int> <chr>     <chr> <chr> <chr>   
+#> 1 get pid NA      <int>        0    NA NA        NA    NA    NA      
+#> # ℹ 3 more variables: launcher <chr>, worker <int>, instance <chr>
 ```
 
 Alternatively, `wait()` is a loop that repeatedly checks tasks and
@@ -153,6 +153,36 @@ task$result[[1]] # return value of the task
 #> [1] 69631
 ```
 
+Here is the full list of output in the `task` object returned by
+`pop()`.
+
+- `name`: the task name if given.
+- `command`: a character string with the R command if `save_command` was
+  set to `TRUE` in `push()`.
+- `result`: a list containing the return value of the R command.
+- `seconds`: number of seconds that the task ran.
+- `seed`: the single integer originally supplied to `push()`, `NA` if
+  `seed` was supplied as `NULL`.
+- `algorithm`: name of the pseudo-random number generator algorithm
+  originally supplied to `push()`, `NA` if `algorithm` was supplied as
+  `NULL`.
+- `error`: the first 2048 characters of the error message if the task
+  threw an error, `NA` otherwise.
+- `trace`: the first 2048 characters of the text of the traceback if the
+  task threw an error, `NA` otherwise.
+- `warnings`: the first 2048 characters. of the text of warning messages
+  that the task may have generated, `NA` otherwise.
+- `launcher`: name of the `crew` launcher where the task ran.
+
+If `seed` and `algorithm` are both non-missing in the output, then you
+can recover the pseudo-random number generator state of the task using
+`set.seed(seed = seed, kind = algorithm)`. However, it is recommended to
+supply `NULL` to these arguments in `push()`, in which case you will
+observe `NA` in the outputs. With `seed` and `algorithm` both `NULL`,
+the random number generator defaults to the recommended widely spaced
+worker-specific L’Ecuyer streams supported by `mirai::nextstream()`. See
+`vignette("parallel", package = "parallel")` for details.
+
 # Functional programming
 
 The
@@ -189,13 +219,12 @@ results <- controller$map(
 )
 
 results
-#> # A tibble: 2 × 11
-#>   name  command result    seconds      seed error trace warnings
-#>   <chr> <chr>   <list>      <dbl>     <int> <chr> <chr> <chr>   
-#> 1 1     NA      <dbl [1]>       0    1.82e9 NA    NA    NA      
-#> 2 2     NA      <dbl [1]>       0    1.82e9 NA    NA    NA      
-#> # ℹ 3 more variables: launcher <chr>, worker <int>,
-#> #   instance <chr>
+#> # A tibble: 2 × 12
+#>   name  command result    seconds  seed algorithm error trace warnings
+#>   <chr> <chr>   <list>      <dbl> <int> <chr>     <chr> <chr> <chr>   
+#> 1 1     NA      <dbl [1]>       0    NA NA        NA    NA    NA      
+#> 2 2     NA      <dbl [1]>       0    NA NA        NA    NA    NA      
+#> # ℹ 3 more variables: launcher <chr>, worker <int>, instance <chr>
 
 as.numeric(results$result)
 #> [1] 14 18
@@ -324,8 +353,9 @@ workers*, and each is problematic in its own way.
 # Risks
 
 The `crew` package has unavoidable risk. It is your responsibility as
-the user to safely use `crew`. Please read the final clause of the
-[software license](https://wlandau.github.io/crew/LICENSE.html).
+the user to safely use `crew`. Please read the [software
+license](https://wlandau.github.io/crew/LICENSE.html) and the
+sub-sections below about specific known risks.
 
 ## Security