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 <[email protected]> --- 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 [email protected] https://www.redhat.com/mailman/listinfo/libguestfs
