Tracking issue for new grant methods

[jamesmunns]

In the 0.4.x release train, I would like to add some new ways to allow for more granular control of grants. The following are currently planned:

Regular grants

• grant_remaining()
  • User will receive a grant 0 < sz <= total_buffer_sz (or receive an error)
  • This will only cause a wrap to the beginning of the ring if exactly
    zero bytes are available at the end of the ring.
  • Maximum possible waste due to skipping: 0 bytes
• grant_largest()
  • User will receive a grant 0 < sz <= total_buffer_sz (or receive an error)
  • This function will find the largest contiguous region available
    (at the end or beginning of the ring).
  • If the region at the beginning was chosen, some bytes at the end of the ring
    will be skipped
  • Maximum possible waste due to skipping: (total_buffer_sz / 2) - 1 bytes
• grant_largest_max(N)
  • User will receive a grant 0 < sz <= N (or receive an error)
  • This function will attempt to find a contiguous region up to sz bytes large.
    If no such region exists, the largest region available (at the end or
    beginning of the ring) will be granted to the user.
  • If the region at the beginning was chosen, some bytes at the end of the ring
    will be skipped
  • Maximum possible waste due to skipping: (total_buffer_sz / 2) - 1 bytes

Split Grants

The following might introduce the concept of "split grants", which provide two
separate contiguous buffers in order to eliminate waste due to splitting, but require
the user to make writes to each buffer.

• split_grant_remaining(N)
  • User will receive a grant containing two segments with a total size of
    0 < (sz_A + sz_B) <= total_buffer_sz (or receive an error)
• split_grant_max_remaining(N)
  • User will receive a grant containing two segments with a total size of
    0 < (sz_A + sz_B) <= N (or receive an error)
  • If the grant requested fits without wraparound, then the sizes of the grants
    will be: sz_A == N, sz_B == 0.
• split_grant_exact(N)
  • User will receive a grant containing two segments with a total size of
    (sz_A + sz_B) == N (or receive an error)
  • If the grant requested fits without wraparound, then the sizes of the grants
    will be: sz_A == N, sz_B == 0.