(internal): lower default value of org-roam-db-gc-threshold (#872)

The high value has been reported to cause significant slowdowns, so we
reset the default, and add documentation for its customization instead.
Ref #834

doc/org-roam.org

@@ -831,6 +831,22 @@ checker, to perform autofixes for the errors. For each error detected,
 =org-roam-doctor= will move the point to the current error, and pop-up a help
 window displaying the error message, as well as the list of actions that can be
 taken provided in =:actions=.
+* Performance Optimization
+** TODO Profiling Key Operations
+** Garbage Collection
+
+During the cache-build process, Org-roam generates a lot of in-memory
+data-structures (such as the Org file's AST), which are discarded after use. These structures are garbage collected at regular intervals (see [[info:elisp#Garbage Collection][info:elisp#Garbage Collection]]).
+
+Org-roam provides the option ~org-roam-db-gc-threshold~ to temporarily change
+the threshold value for GC to be triggered during these memory-intensive
+operations. To reduce the number of garbage collection processes, one may set
+~org-roam-db-gc-threshold~ to a high value (such as ~most-positive-fixnum~):
+
+#+BEGIN_SRC emacs-lisp
+  (setq org-roam-db-gc-threshold most-positive-fixnum)
+#+END_SRC
+
 * _ Copying
 :PROPERTIES:
 :COPYING:    t

doc/org-roam.texi

@@ -78,6 +78,7 @@ General Public License for more details.
 * Roam Protocol::
 * Daily Notes::
 * Diagnosing and Repairing Files::
+* Performance Optimization::
 * Appendix::
 * FAQ::
 
@@ -124,6 +125,11 @@ Roam Protocol
 * The @samp{roam-file} protocol::
 * The @samp{roam-ref} Protocol::
 
+Performance Optimization
+
+* Profiling Key Operations::
+* Garbage Collection::
+
 Appendix
 
 * Note-taking Workflows::
@@ -1128,6 +1134,32 @@ checker, to perform autofixes for the errors. For each error detected,
 window displaying the error message, as well as the list of actions that can be
 taken provided in @samp{:actions}.
 
+@node Performance Optimization
+@chapter Performance Optimization
+
+@menu
+* Profiling Key Operations::
+* Garbage Collection::
+@end menu
+
+@node Profiling Key Operations
+@section @strong{TODO} Profiling Key Operations
+
+@node Garbage Collection
+@section Garbage Collection
+
+During the cache-build process, Org-roam generates a lot of in-memory
+data-structures (such as the Org file's AST), which are discarded after use. These structures are garbage collected at regular intervals (see @ref{Garbage Collection,info:elisp#Garbage Collection,,elisp,}).
+
+Org-roam provides the option @code{org-roam-db-gc-threshold} to temporarily change
+the threshold value for GC to be triggered during these memory-intensive
+operations. To reduce the number of garbage collection processes, one may set
+@code{org-roam-db-gc-threshold} to a high value (such as @code{most-positive-fixnum}):
+
+@lisp
+(setq org-roam-db-gc-threshold most-positive-fixnum)
+@end lisp
+
 @node Appendix
 @chapter Appendix
 

org-roam-db.el

@@ -60,13 +60,18 @@ when used with multiple Org-roam instances."
   :type 'string
   :group 'org-roam)
 
-(defcustom org-roam-db-gc-threshold most-positive-fixnum
+(defcustom org-roam-db-gc-threshold gc-cons-threshold
   "The value to temporarily set the `gc-cons-threshold' threshold to.
 During large, heavy operations like `org-roam-db-build-cache',
 many GC operations happen because of the large number of
 temporary structures generated (e.g. parsed ASTs). Temporarily
 increasing `gc-cons-threshold' will help reduce the number of GC
-operations, at the cost of temporary memory usage."
+operations, at the cost of temporary memory usage.
+
+This defaults to the original value of `gc-cons-threshold', but
+tweaking this number may lead to better overall performance. For
+example, to reduce the number of GCs, one may set it to a large
+value like `most-positive-fixnum'."
   :type 'int
   :group 'org-roam)
 

tests/test-org-roam-perf.el

@@ -45,7 +45,7 @@
     (pcase (benchmark-run 1 (org-roam-db-build-cache t))
       (`(,time ,gcs ,time-in-gc)
        (message "Elapsed time: %fs (%fs in %d GCs)" time time-in-gc gcs)
-       (expect time :to-be-less-than 70))))
+       (expect time :to-be-less-than 90))))
   (it "builds quickly without change"
     (pcase (benchmark-run 1 (org-roam-db-build-cache))
       (`(,time ,gcs ,time-in-gc)