diff --git a/doc/org-roam.org b/doc/org-roam.org index ac7485b..9f78da1 100644 --- a/doc/org-roam.org +++ b/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 diff --git a/doc/org-roam.texi b/doc/org-roam.texi index 37db469..cb6f715 100644 --- a/doc/org-roam.texi +++ b/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 diff --git a/org-roam-db.el b/org-roam-db.el index 6c3e491..0f4f9d9 100644 --- a/org-roam-db.el +++ b/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) diff --git a/tests/test-org-roam-perf.el b/tests/test-org-roam-perf.el index d9ffa13..5479560 100644 --- a/tests/test-org-roam-perf.el +++ b/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)