From 808e03f4e2ab349463e12af67ecde2e7f1d0f1da Mon Sep 17 00:00:00 2001
From: Magnus Thor Torfason <m@zulutime.net>
Date: Mon, 25 Mar 2024 04:03:39 +0000
Subject: [PATCH] fix #64: expand docs on requests to httd(daemon=TRUE) in same
 process (#65)

---
 R/static.R           | 10 +++++++++-
 man/server_config.Rd | 10 +++++++++-
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/R/static.R b/R/static.R
index af9c5ff..e08612c 100644
--- a/R/static.R
+++ b/R/static.R
@@ -188,7 +188,15 @@ watch_dir = function(
 #'   \code{options(servr.daemon = TRUE)}); if this option was not set,
 #'   \code{daemon = TRUE} if a command line argument \code{-d} was passed to R
 #'   (through \command{Rscript}), or the server is running in an interactive R
-#'   session.
+#'   session. Note, however, that even though the server does not block the
+#'   current R session, it is running in the same single-threaded process.
+#'   Therefore, if a request is made from this same session, the client and
+#'   server \emph{will} block each other. If this is your use case, a better
+#'   solution is to use a package such as \code{callr} to run a \code{servr}
+#'   in a separate process, e.g, \code{rx <- callr::r_bg(function()
+#'   servr::httd(daemon = FALSE)); do_stuff(); rx$kill()} (the
+#'   \code{do_stuff()} function may want to wait a couple of seconds before
+#'   making requests, to allow the server time to start).
 #' @param interval The time interval used to check if an HTML page needs to be
 #'   rebuilt (by default, it is checked every second).
 #' @param baseurl The base URL (the full URL will be
diff --git a/man/server_config.Rd b/man/server_config.Rd
index 45a6381..94fd6a1 100644
--- a/man/server_config.Rd
+++ b/man/server_config.Rd
@@ -46,7 +46,15 @@ global option \code{getOption('servr.daemon')} (e.g., you can set
 \code{options(servr.daemon = TRUE)}); if this option was not set,
 \code{daemon = TRUE} if a command line argument \code{-d} was passed to R
 (through \command{Rscript}), or the server is running in an interactive R
-session.}
+session. Note, however, that even though the server does not block the
+current R session, it is running in the same single-threaded process.
+Therefore, if a request is made from this same session, the client and
+server \emph{will} block each other. If this is your use case, a better
+solution is to use a package such as \code{callr} to run a \code{servr}
+in a separate process, e.g, \code{rx <- callr::r_bg(function()
+servr::httd(daemon = FALSE)); do_stuff(); rx$kill()} (the
+\code{do_stuff()} function may want to wait a couple of seconds before
+making requests, to allow the server time to start).}
 
 \item{interval}{The time interval used to check if an HTML page needs to be
 rebuilt (by default, it is checked every second).}