Re: [PATCH 1/8] btrfs-progs: document squotas

[Josef Bacik <josef@toxicpanda.com>]

On Wed, Jul 05, 2023 at 04:36:20PM -0700, Boris Burkov wrote:
> Document the new options in btrfs quota and mkfs.btrfs. Also, add a
> section to the long form qgroups document about squotas.
> 
> Signed-off-by: Boris Burkov <boris@bur.io>
> ---
>  Documentation/btrfs-quota.rst    |  7 +++-
>  Documentation/ch-quota-intro.rst | 59 ++++++++++++++++++++++++++++++++
>  Documentation/mkfs.btrfs.rst     |  6 ++++
>  3 files changed, 71 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/btrfs-quota.rst b/Documentation/btrfs-quota.rst
> index 830e9059a..d5e08330e 100644
> --- a/Documentation/btrfs-quota.rst
> +++ b/Documentation/btrfs-quota.rst
> @@ -47,9 +47,14 @@ SUBCOMMAND
>  disable <path>
>          Disable subvolume quota support for a filesystem.
>  
> -enable <path>
> +enable [options] <path>
>          Enable subvolume quota support for a filesystem.
>  
> +        ``Options``
> +
> +	-s|--simple
> +		use simple quotas (squotas) instead of qgroups
> +
>  rescan [options] <path>
>          Trash all qgroup numbers and scan the metadata again with the current config.
>  
> diff --git a/Documentation/ch-quota-intro.rst b/Documentation/ch-quota-intro.rst
> index 351772d10..a69e35c8a 100644
> --- a/Documentation/ch-quota-intro.rst
> +++ b/Documentation/ch-quota-intro.rst
> @@ -194,3 +194,62 @@ but some snapshots for backup purposes are being created by the system.  The
>  user's snapshots should be accounted to the user, not the system.  The solution
>  is similar to the one from section 'Accounting snapshots to the user', but do
>  not assign system snapshots to user's qgroup.
> +
> +Simple Quotas (squotas)
> +^^^^^^^^^^^^^^^^^^^^^^^
> +
> +As detailed in this document, qgroups can handle many complex extent sharing
> +and unsharing scenarios while maintaining an accurate count of exclusive and
> +shared usage. However, this flexibility comes at a cost: many of the
> +computations are global, in the sense that we must count up the number of trees
> +referring to an extent after its references change. This can slow down
> +transaction commits and lead to unacceptable latencies, especially in cases
> +where snapshots scale up.
> +
> +To work around this limitation of qgroups, btrfs also supports a second set of
> +quota semantics: simple quotas or squotas. Squotas fully share the qgroups API
> +and hierarchical model, but do not track shared vs. exclusive usage. Instead,
> +they account all extents to the subvolume that first allocated it. With a bit
> +of new bookkeeping, this allows all accounting decisions to be local to the
> +allocation or freeing operation that deals with the extents themselves, and
> +fully avoids the complex and costly back-reference resolutions.
> +
> +``Example``
> +
> +To illustrate the difference between squotas and qgroups, consider the following
> +basic example assuming a nodesize of 16KiB.
> +
> +1. create subvolume 256
> +1. rack up 1GiB of data and metadata usage in 256

Mis-numbered.  Thanks,

Josef