diff --git a/README.Rmd b/README.Rmd index df6d7122..9e2a81bb 100644 --- a/README.Rmd +++ b/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 diff --git a/README.md b/README.md index 50d422bd..4dc49d07 100644 --- a/README.md +++ b/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 -#> -#> 1 get pid NA 0 1.78e9 NA NA NA 372d50b… 1 -#> # ℹ 1 more variable: instance +#> # A tibble: 1 × 12 +#> name command result seconds seed algorithm error trace warnings +#> +#> 1 get pid NA 0 NA NA NA NA NA +#> # ℹ 3 more variables: launcher , worker , instance ``` 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 -#> -#> 1 1 NA 0 1.82e9 NA NA NA -#> 2 2 NA 0 1.82e9 NA NA NA -#> # ℹ 3 more variables: launcher , worker , -#> # instance +#> # A tibble: 2 × 12 +#> name command result seconds seed algorithm error trace warnings +#> +#> 1 1 NA 0 NA NA NA NA NA +#> 2 2 NA 0 NA NA NA NA NA +#> # ℹ 3 more variables: launcher , worker , instance 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