|
5 | 5 | #' |
6 | 6 | #' @param quiet A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`. |
7 | 7 | #' @keywords internal |
8 | | -global_quiet_param <- function(quiet){ |
| 8 | +global_quiet_param <- function(quiet) { |
9 | 9 | # this is just a placeholder for global quiet parameter |
10 | 10 | } |
| 11 | + |
| 12 | +#' @title rJava Path-Locking Documentation |
| 13 | +#' |
| 14 | +#' @description |
| 15 | +#' Documentation template for rJava path-locking behavior. |
| 16 | +#' |
| 17 | +#' @section rJava Path-Locking: |
| 18 | +#' **Important for \strong{rJava} Users**: This function sets environment variables |
| 19 | +#' (JAVA_HOME, PATH) that affect both command-line Java tools and \strong{rJava} initialization. |
| 20 | +#' However, due to \strong{rJava}'s path-locking behavior when \code{\link[rJava]{.jinit}} is called |
| 21 | +#' (see \url{https://github.com/s-u/rJava/issues/25}, \url{https://github.com/s-u/rJava/issues/249}, and \url{https://github.com/s-u/rJava/issues/334}), |
| 22 | +#' this function must be called **BEFORE** \code{\link[rJava]{.jinit}} is invoked. Once \code{\link[rJava]{.jinit}} |
| 23 | +#' initializes, the Java version is locked for that R session and cannot be changed without restarting R. |
| 24 | +#' |
| 25 | +#' \code{\link[rJava]{.jinit}} is invoked (and Java locked) when you: |
| 26 | +#' \itemize{ |
| 27 | +#' \item Explicitly call \code{library(rJava)} |
| 28 | +#' \item Load any package that imports \strong{rJava} (which auto-loads it as a dependency) |
| 29 | +#' \item Even just use IDE autocomplete with \code{rJava::} (this triggers initialization!) |
| 30 | +#' \item Call any \strong{rJava}-dependent function |
| 31 | +#' } |
| 32 | +#' |
| 33 | +#' Once any of these happen, the Java version used by \strong{rJava} for that session is locked in. |
| 34 | +#' For command-line Java tools that don't use \strong{rJava}, this function can be called at any |
| 35 | +#' time to switch Java versions for subsequent system calls. |
| 36 | +#' |
| 37 | +#' @keywords internal |
| 38 | +rjava_path_locking_note <- function() { |
| 39 | + # Placeholder for rJava path-locking documentation |
| 40 | +} |
| 41 | + |
| 42 | +#' @title Global Use Cache Parameter |
| 43 | +#' |
| 44 | +#' @description |
| 45 | +#' Documentation for the `.use_cache` parameter, used for performance optimization. |
| 46 | +#' |
| 47 | +#' @param .use_cache A `logical` value controlling caching behavior. If `FALSE` (default), |
| 48 | +#' performs a fresh check each time (safe, reflects current state). If `TRUE`, uses |
| 49 | +#' session-scoped cached results for performance in loops or repeated calls. |
| 50 | +#' |
| 51 | +#' **Caching Behavior:** |
| 52 | +#' - Session-scoped: Cache is cleared when R restarts |
| 53 | +#' - Key-based for version checks: Changes to JAVA_HOME create new cache entries |
| 54 | +#' - System-wide for scanning: Always recalculates current default Java |
| 55 | +#' |
| 56 | +#' **Performance Benefits:** |
| 57 | +#' - First call: ~37-209ms (depending on operation) |
| 58 | +#' - Cached calls: <1ms |
| 59 | +#' - Prevents 30-100ms delays on every call in performance-critical code |
| 60 | +#' |
| 61 | +#' **When to Enable:** |
| 62 | +#' - Package initialization code (`.onLoad` or similar) |
| 63 | +#' - Loops calling the same function multiple times |
| 64 | +#' - Performance-critical paths with frequent version checks |
| 65 | +#' |
| 66 | +#' **When to Keep Default (FALSE):** |
| 67 | +#' - Interactive use (one-off checks) |
| 68 | +#' - When you need current data reflecting recent Java installations |
| 69 | +#' - General-purpose function calls that aren't time-critical |
| 70 | +#' |
| 71 | +#' @keywords internal |
| 72 | +global_use_cache_param <- function(.use_cache) { |
| 73 | + # this is just a placeholder for global .use_cache parameter |
| 74 | +} |
0 commit comments