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

[Bagas Sanjaya <bagasdotme@gmail.com>]

On 11/20/22 00:24, Ananda Badmaev wrote:
> 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.
> 

OK, thanks.

Next time, don't forget to Cc linux-doc list for patches touching Documentation/.
Adding one since you don't.

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