Re: [Libguestfs] [nbdkit PATCH] filters: Improve docs on .prepare prerequisites

Since .prepare is called before client negotiation has completed, filters have an additional burden to ensure prerequisite functions are called in order to avoid triggering assertions in backend.c. See also: https://bugzilla.redhat.com/show_bug.cgi?id=1855330, https://www.redhat.com/archives/libguestfs/2020-July/msg00041.html Signed-off-by: Eric Blake <eblake(a)redhat.com&gt; --- docs/nbdkit-filter.pod | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/nbdkit-filter.pod b/docs/nbdkit-filter.pod index acac3e50..3d201309 100644 --- a/docs/nbdkit-filter.pod +++ b/docs/nbdkit-filter.pod @@ -383,14 +383,20 @@ connection (C<.finalize>). For example if you need to scan the underlying disk to check for a partition table, you could do it in your C<.prepare> method (calling -the plugin's C<.pread> method via C<next_ops>). Or if you need to -cleanly update superblock data in the image on close you can do it in -your C<.finalize> method (calling the plugin's C<.pwrite> method). -Doing these things in the filter's C<.open> or C<.close> method is not -possible. +the plugin's C<.get_size> and C<.pread> methods via C<next_ops>). Or +if you need to cleanly update superblock data in the image on close +you can do it in your C<.finalize> method (calling the plugin's +C<.pwrite> method). Doing these things in the filter's C<.open> or +C<.close> method is not possible. For C<.prepare>, the value of C<readonly> is the same as was passed to -C<.open>, declaring how this filter will be used. +C<.open>, declaring how this filter will be used. When calling plugin +functions during C<.prepare>, the filter must ensure that prerequisite +functions have succeeded (for example, calling C<.pwrite>) requires +checking both C<.get_size> and C<.can_write>); while these +prerequisites are automatically handled in most other cases thanks to +client negotiation, the timing of C<.prepare> comes before client +negotiation has completed.

There is no C<next_ops-E<gt>prepare> or C<next_ops-E<gt>finalize>. Unlike other filter methods, prepare and finalize are not chained -- 2.27.0 _______________________________________________ Libguestfs mailing list Libguestfs(a)redhat.com https://www.redhat.com/mailman/listinfo/libguestfs