Re: [PATCH v7] mm: add zblock - new allocator for use via zpool API

[Bagas Sanjaya <bagasdotme@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4687 bytes --]

On Sat, Nov 19, 2022 at 11:21:59AM +0300, ananda wrote:
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _block:

Why is the anchor label for doc title _block? Why not _zblock instead?

> +
> +======
> +zblock
> +======
> +
> +Zblock stores integer number of compressed objects per block. These
> +blocks consist of several consecutive physical pages (from 1 to 8) and
> +are arranged in lists. The range from 0 to PAGE_SIZE is divided into the
> +number of intervals corresponding to the number of lists and each list
> +only operates objects of size from its interval. Thus the block lists are
> +isolated from each other, which makes it possible to simultaneously
> +perform actions with several objects from different lists.
> +
> +Blocks make it possible to densely arrange objects of various sizes
> +resulting in low internal fragmentation. Also this allocator tries to fill
> +incomplete blocks instead of adding new ones thus in many cases providing
> +a compression ratio substantially higher than z3fold and zbud. Zblock does
> +not require MMU and also is superior to zsmalloc with regard to the worst
> +execution times, thus allowing for better response time and real-time
> +characteristics of the whole system.
> +
> +Like z3fold and zsmalloc zblock_alloc() does not return a dereferenceable
> +pointer. Instead, it returns an unsigned long handle which encodes actual
> +location of the allocated object.
> +
> +Unlike zbud and z3fold zblock works well with objects of various sizes - both
> +highly compressed and poorly compressed including cases where both types
> +are present.

The wording can be better (including doc title label suggestion):

---- >8 ----

diff --git a/Documentation/mm/zblock.rst b/Documentation/mm/zblock.rst
index 5008ce90b54bef..1eb91a8d175dbb 100644
--- a/Documentation/mm/zblock.rst
+++ b/Documentation/mm/zblock.rst
@@ -1,31 +1,31 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-.. _block:
+.. _zblock:
 
 ======
 zblock
 ======
 
-Zblock stores integer number of compressed objects per block. These
-blocks consist of several consecutive physical pages (from 1 to 8) and
-are arranged in lists. The range from 0 to PAGE_SIZE is divided into the
-number of intervals corresponding to the number of lists and each list
-only operates objects of size from its interval. Thus the block lists are
-isolated from each other, which makes it possible to simultaneously
-perform actions with several objects from different lists.
+Zblock stores integer number of compressed objects per block. These blocks
+consist of several consecutive physical pages (from 1 to 8) and are arranged in
+lists. The range from 0 to PAGE_SIZE is divided into the number of intervals
+corresponding to each list and these only operates on objects of size from the
+corresponding interval. Thus the block lists are isolated from each other,
+which makes it possible to simultaneously perform actions with several objects
+from different lists.
 
-Blocks make it possible to densely arrange objects of various sizes
+With zblock, it is possible to densely arrange objects of various sizes,
 resulting in low internal fragmentation. Also this allocator tries to fill
-incomplete blocks instead of adding new ones thus in many cases providing
-a compression ratio substantially higher than z3fold and zbud. Zblock does
-not require MMU and also is superior to zsmalloc with regard to the worst
+incomplete blocks instead of adding new ones. As a result, in many cases it
+provides a compression ratio substantially higher than z3fold and zbud. Zblock
+does not require MMU and also is superior to zsmalloc with regard to the worst
 execution times, thus allowing for better response time and real-time
 characteristics of the whole system.
 
-Like z3fold and zsmalloc zblock_alloc() does not return a dereferenceable
-pointer. Instead, it returns an unsigned long handle which encodes actual
-location of the allocated object.
+Like similar allocation method from z3fold and zsmalloc, zblock_alloc() does
+not return a dereferenceable pointer. Instead, it returns an unsigned long
+handle which encodes actual location of the allocated object.
 
-Unlike zbud and z3fold zblock works well with objects of various sizes - both
-highly compressed and poorly compressed including cases where both types
-are present.
+Unlike zbud and z3fold, zblock works well with objects of various sizes -
+including but not limited to highly compressed and poorly compressed, as well
+as cases where both object types exist.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]