From 58cde923414bbc313677116684505b961477c057 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Fri, 7 Jun 2019 16:39:22 -0700 Subject: [PATCH] Fix commentary about fixnums and hashes. --- src/fns.c | 14 +++++--------- src/lisp.h | 28 +++++++++++++--------------- 2 files changed, 18 insertions(+), 24 deletions(-) diff --git a/src/fns.c b/src/fns.c index 4bb525b89e9..ddd08af994a 100644 --- a/src/fns.c +++ b/src/fns.c @@ -3866,8 +3866,7 @@ cmpfn_user_defined (struct hash_table_test *ht, } /* Value is a hash code for KEY for use in hash table H which uses - `eq' to compare keys. The hash code returned is guaranteed to fit - in a Lisp integer. */ + `eq' to compare keys. The value is at most INTMASK. */ static EMACS_UINT hashfn_eq (struct hash_table_test *ht, Lisp_Object key) @@ -3876,8 +3875,7 @@ hashfn_eq (struct hash_table_test *ht, Lisp_Object key) } /* Value is a hash code for KEY for use in hash table H which uses - `equal' to compare keys. The hash code returned is guaranteed to fit - in a Lisp integer. */ + `equal' to compare keys. The value is at most INTMASK. */ EMACS_UINT hashfn_equal (struct hash_table_test *ht, Lisp_Object key) @@ -3886,8 +3884,7 @@ hashfn_equal (struct hash_table_test *ht, Lisp_Object key) } /* Value is a hash code for KEY for use in hash table H which uses - `eql' to compare keys. The hash code returned is guaranteed to fit - in a Lisp integer. */ + `eql' to compare keys. The value is at most INTMASK. */ EMACS_UINT hashfn_eql (struct hash_table_test *ht, Lisp_Object key) @@ -3898,8 +3895,7 @@ hashfn_eql (struct hash_table_test *ht, Lisp_Object key) } /* Value is a hash code for KEY for use in hash table H which uses as - user-defined function to compare keys. The hash code returned is - guaranteed to fit in a Lisp integer. */ + user-defined function to compare keys. The value is at most INTMASK. */ static EMACS_UINT hashfn_user_defined (struct hash_table_test *ht, Lisp_Object key) @@ -4417,7 +4413,7 @@ hash_string (char const *ptr, ptrdiff_t len) } /* Return a hash for string PTR which has length LEN. The hash - code returned is guaranteed to fit in a Lisp integer. */ + code returned is at most INTMASK. */ static EMACS_UINT sxhash_string (char const *ptr, ptrdiff_t len) diff --git a/src/lisp.h b/src/lisp.h index 5bd88f32e6e..77fc22d1187 100644 --- a/src/lisp.h +++ b/src/lisp.h @@ -241,11 +241,11 @@ enum Lisp_Bits /* Number of bits in a Lisp_Object value, not counting the tag. */ VALBITS = EMACS_INT_WIDTH - GCTYPEBITS, - /* Number of bits in a Lisp fixnum value, not counting the tag. */ + /* Number of bits in a fixnum value, not counting the tag. */ FIXNUM_BITS = VALBITS + 1 }; -/* Number of bits in a Lisp fixnum tag; can be used in #if. */ +/* Number of bits in a fixnum tag; can be used in #if. */ DEFINE_GDB_SYMBOL_BEGIN (int, INTTYPEBITS) #define INTTYPEBITS (GCTYPEBITS - 1) DEFINE_GDB_SYMBOL_END (INTTYPEBITS) @@ -473,7 +473,7 @@ typedef EMACS_INT Lisp_Word; data type, read the comments after Lisp_Fwd_Type definition below. */ -/* Lisp integers use 2 tags, to give them one extra bit, thus +/* Fixnums use 2 tags, to give them one extra bit, thus extending their range from, e.g., -2^28..2^28-1 to -2^29..2^29-1. */ #define INTMASK (EMACS_INT_MAX >> (INTTYPEBITS - 1)) #define case_Lisp_Int case Lisp_Int0: case Lisp_Int1 @@ -1160,8 +1160,7 @@ INLINE EMACS_INT also work when USE_LSB_TAG; this is to aid future maintenance when the lisp_h_* macros are eventually removed. */ -/* Make a Lisp integer representing the value of the low order - bits of N. */ +/* Make a fixnum representing the value of the low order bits of N. */ INLINE Lisp_Object make_fixnum (EMACS_INT n) { @@ -1207,7 +1206,7 @@ XFIXNAT (Lisp_Object a) #endif /* ! USE_LSB_TAG */ -/* Extract A's value as an unsigned integer. */ +/* Extract A's value as an unsigned integer in the range 0..INTMASK. */ INLINE EMACS_UINT XUFIXNUM (Lisp_Object a) { @@ -1215,9 +1214,8 @@ XUFIXNUM (Lisp_Object a) return USE_LSB_TAG ? i >> INTTYPEBITS : i & INTMASK; } -/* Return A's (Lisp-integer sized) hash. Happens to be like XUFIXNUM - right now, but XUFIXNUM should only be applied to objects we know are - integers. */ +/* Return A's hash, which is in the range 0..INTMASK. Although XHASH (A) == + XUFIXNUM (A) currently, XUFIXNUM should be applied only to fixnums. */ INLINE EMACS_INT (XHASH) (Lisp_Object a) @@ -1242,7 +1240,7 @@ INLINE bool return lisp_h_EQ (x, y); } -/* True if the possibly-unsigned integer I doesn't fit in a Lisp fixnum. */ +/* True if the possibly-unsigned integer I doesn't fit in a fixnum. */ #define FIXNUM_OVERFLOW_P(i) \ (! ((0 <= (i) || MOST_NEGATIVE_FIXNUM <= (i)) && (i) <= MOST_POSITIVE_FIXNUM)) @@ -1315,7 +1313,7 @@ INLINE bool #define XSETCONDVAR(a, b) (XSETPSEUDOVECTOR (a, b, PVEC_CONDVAR)) /* Efficiently convert a pointer to a Lisp object and back. The - pointer is represented as a Lisp integer, so the garbage collector + pointer is represented as a fixnum, so the garbage collector does not know about it. The pointer should not have both Lisp_Int1 bits set, which makes this conversion inherently unportable. */ @@ -2410,8 +2408,8 @@ static float const DEFAULT_REHASH_THRESHOLD = 0.8125; static float const DEFAULT_REHASH_SIZE = 1.5 - 1; -/* Combine two integers X and Y for hashing. The result might not fit - into a Lisp integer. */ +/* Combine two integers X and Y for hashing. The result might exceed + INTMASK. */ INLINE EMACS_UINT sxhash_combine (EMACS_UINT x, EMACS_UINT y) @@ -2419,7 +2417,7 @@ sxhash_combine (EMACS_UINT x, EMACS_UINT y) return (x << 4) + (x >> (EMACS_INT_WIDTH - 4)) + y; } -/* Hash X, returning a value that fits into a fixnum. */ +/* Hash X, returning a value in the range 0..INTMASK. */ INLINE EMACS_UINT SXHASH_REDUCE (EMACS_UINT x) @@ -2501,7 +2499,7 @@ struct Lisp_Misc_Ptr extern Lisp_Object make_misc_ptr (void *); /* A mint_ptr object OBJ represents a C-language pointer P efficiently. - Preferably (and typically), OBJ is a Lisp integer I such that + Preferably (and typically), OBJ is a fixnum I such that XFIXNUMPTR (I) == P, as this represents P within a single Lisp value without requiring any auxiliary memory. However, if P would be damaged by being tagged as an integer and then untagged via -- 2.39.2