Re: Proposal: block-based vector allocator

[Eli Zaretskii]

> Date: Fri, 08 Jun 2012 09:50:15 +0400
> From: Dmitry Antipov <address@hidden>
> Cc: address@hidden
> 
> OK, last call for comments, with internals.texi tweaks
> and ChangeLog entries...

Thanks.  Allow me a few minor comments and suggestions regarding the
documentation:

> address@hidden vectors and objects looks like a vectors

This index entry is problematic in several ways:

  . it is too long to be useful
  . it is grammatically incorrect ("objects looks")
  . most importantly, it is not a phrase a reader is likely to think
    of when she needs to find this information

The way to write good concept index entries is to come up with phrases
that _you_ might have in mind for locating description of the issues
documented in the text being indexed.

Based on the text, I suggest these 2 index entries:

 @cindex vector-like objects, storage
 @cindex storage of vector-like Lisp objects

(The reason for two permutations is to facilitate the "i TAB"
completion of index entries, when the reader looks for information
about storage of Lisp object.)

> +  Beyond the basic vector, a lot of objects like window, buffer, and
> +frame are managed as if they're vectors.
                     ^^^^^^^^^^^^^^^^^^^^^
"as if they were vectors" is more grammatically correct.

> +                                          So, all corresponding data
> +types includes the field @code{struct vectorlike_header}, where
         ^^^^^^^^
"include", in plural.

> address@hidden points to the next buffer, in the chain of all
> +buffers (including killed buffers), and @code{header.next.vector} points
> +to the next vector in a free list.  For small vectors allocated from vector
> +blocks, @code{header.next.nbytes} is the vector's memory footprint.

I would rephrase slightly:

  The corresponding C data structures include the
  @code{struct vectorlike_header} field whose @code{next} field points
  to the next object in the chain: @code{header.next.buffer} points to
  the next buffer (which could be a killed buffer), and
  @code{header.next.vector} points to the next vector in a free list.
  If a vector is small (smaller than NNN bytes), then
  @code{header.next.nbytes} contains the vector data.

(And please fill in the value of NNN.)

> +to create largest possible free areas; if free area occupies the whole 4k
> +block, the block is freed.

"if a free area spans a complete 4K block, that block is freed"

> +                            Otherwise, the free area is recorded
> +to a free list array, where each entry corresponds to a free list
   ^^^^^^^^^^^^^^^^^^^^
"in a free list array".

> +of areas of the same size. Large vectors, buffers, and other large objects
                            ^^
Two spaces, please.

> +are individually allocated and freed using @code{malloc} and @code{free}.

This is inaccurate, at least for buffer text and strings.  They are
allocated using either mmap or ralloc.c functions.

Thanks.