[Emacs-diffs] master 3331703: Improve documentation of hash-code functions

[Eli Zaretskii]

branch: master
commit 333170348ba83069c1f460af70e9add28d57da2a
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of hash-code functions
    
    * src/fns.c (Fsxhash_eq, Fsxhash_eql, Fsxhash_equal):
    * doc/lispref/hash.texi (Defining Hash): Warn against assuming
    that sxhash returns consistent results.
---
 doc/lispref/hash.texi |  5 +++++
 src/fns.c             | 12 +++++++++---
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 5aaf312..9b900e6 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -333,6 +333,11 @@ and equal-looking objects are considered the same key.
 (make-hash-table :test 'contents-hash)
 @end example
 
+Lisp programs should @emph{not} rely on hash codes being preserved
+between Emacs sessions, as the implementation of the hash functions
+uses some details of the object storage that can change between
+sessions and between different architectures.
+
 @node Other Hash
 @section Other Hash Table Functions
 
diff --git a/src/fns.c b/src/fns.c
index eaa2c07..fd0c7fc 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -4695,7 +4695,9 @@ sxhash (Lisp_Object obj, int depth)
 
 DEFUN ("sxhash-eq", Fsxhash_eq, Ssxhash_eq, 1, 1, 0,
        doc: /* Return an integer hash code for OBJ suitable for `eq'.
-If (eq A B), then (= (sxhash-eq A) (sxhash-eq B)).  */)
+If (eq A B), then (= (sxhash-eq A) (sxhash-eq B)).
+
+Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
   (Lisp_Object obj)
 {
   return make_fixnum (hashfn_eq (NULL, obj));
@@ -4703,7 +4705,9 @@ If (eq A B), then (= (sxhash-eq A) (sxhash-eq B)).  */)
 
 DEFUN ("sxhash-eql", Fsxhash_eql, Ssxhash_eql, 1, 1, 0,
        doc: /* Return an integer hash code for OBJ suitable for `eql'.
-If (eql A B), then (= (sxhash-eql A) (sxhash-eql B)).  */)
+If (eql A B), then (= (sxhash-eql A) (sxhash-eql B)).
+
+Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
   (Lisp_Object obj)
 {
   return make_fixnum (hashfn_eql (NULL, obj));
@@ -4711,7 +4715,9 @@ If (eql A B), then (= (sxhash-eql A) (sxhash-eql B)).  */)
 
 DEFUN ("sxhash-equal", Fsxhash_equal, Ssxhash_equal, 1, 1, 0,
        doc: /* Return an integer hash code for OBJ suitable for `equal'.
-If (equal A B), then (= (sxhash-equal A) (sxhash-equal B)).  */)
+If (equal A B), then (= (sxhash-equal A) (sxhash-equal B)).
+
+Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
   (Lisp_Object obj)
 {
   return make_fixnum (hashfn_equal (NULL, obj));