03/10: database: document extra registration requirements.

[guix-commits]

civodul pushed a commit to branch master
in repository guix.

commit a05c31ab3007a7a60f735ed7405fb9c54be1728d
Author: Caleb Ristvedt <caleb.ristvedt@cune.org>
AuthorDate: Wed Jul 8 11:33:23 2020 -0500

    database: document extra registration requirements.
    
    It's necessary that store items be locked and protected from garbage
    collection while they are being registered.  This documents that.
    
    * guix/store/database.scm (register-path, register-items): document GC
      protection and locking requirements.
    
    Signed-off-by: Ludovic Courtès <ludo@gnu.org>
---
 guix/store/database.scm | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/guix/store/database.scm b/guix/store/database.scm
index 50b66ce..e39a160 100644
--- a/guix/store/database.scm
+++ b/guix/store/database.scm
@@ -397,7 +397,10 @@ absolute file name to the state directory of the store 
being initialized.
 Return #t on success.
 
 Use with care as it directly modifies the store!  This is primarily meant to
-be used internally by the daemon's build hook."
+be used internally by the daemon's build hook.
+
+PATH must be protected from GC and locked during execution of this, typically
+by adding it as a temp-root."
   (define db-file
     (store-database-file #:prefix prefix
                          #:state-directory state-directory))
@@ -423,7 +426,9 @@ be used internally by the daemon's build hook."
   "Register all of ITEMS, a list of <store-info> records as returned by
 'read-reference-graph', in DB.  ITEMS must be in topological order (with
 leaves first.)  REGISTRATION-TIME must be the registration time to be recorded
-in the database; #f means \"now\".  Write a progress report to LOG-PORT."
+in the database; #f means \"now\".  Write a progress report to LOG-PORT.  All
+of ITEMS must be protected from GC and locked during execution of this,
+typically by adding them as temp-roots."
   (define store-dir
     (if prefix
         (string-append prefix %storedir)