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

[Ananda Badmaev <a.badmaev@clicknet.pro>]

19.11.2022 15:46, Bagas Sanjaya пишет:
> 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?
>

This is a typo. It will be fixed in the next version if necessary.


>> +
>> +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.
> 

I'm not sure there's much point in simply reformulating the text, but in 
the next version it may be worth a bit changing this text along with 
other changes.