1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
=head1 NAME
nbdkit_shutdown,
nbdkit_disconnect - request shutdown or client disconnection
=head1 SYNOPSIS
#include <nbdkit-plugin.h>
void nbdkit_shutdown (void);
void nbdkit_disconnect (int force);
=head1 DESCRIPTION
Plugins and filters can call L<exit(3)> in the configuration phase
(before and including C<.get_ready>, but not in connected callbacks).
Once nbdkit has started serving connections, plugins and filters
should not call L<exit(3)>. However they may instruct nbdkit to shut
down by calling C<nbdkit_shutdown>, or to disconnect a single client
by calling C<nbdkit_disconnect>.
=head2 nbdkit_shutdown
C<nbdkit_shutdown> requests nbdkit to shut down asynchronously and
returns (B<note> that it does B<not> exit the process immediately).
It ensures that the plugin and all filters are unloaded cleanly which
may take some time. Further callbacks from nbdkit into the plugin or
filter may occur after you have called this.
=head2 nbdkit_disconnect
C<nbdkit_disconnect> requests that the current client connection be
disconnected. It does not affect other connections, and it does not
stop the same client from trying to reconnect.
It is only useful from connected callbacks — that is, after (but not
including) C<.open>, and before C<.close>. To reject a client in
C<.preconnect>, C<.open> or C<.list_exports> you should return an
error instead.
If C<force> is true, nbdkit will disconnect the client immediately,
and the client will not receive any response to the current command or
any other commands in flight in parallel threads. If C<force> is
false, nbdkit will not accept any new commands from the client
(failing all commands other than C<NBD_CMD_DISC> with C<ESHUTDOWN>),
but will allow existing commands to complete gracefully. Either way,
the next callback for the current connection should be C<.close>.
=head1 LANGUAGE BINDINGS
In L<nbdkit-ocaml-plugin(3)>:
NBDKit.shutdown : unit -> unit
NBDKit.disconnect : bool -> unit
In L<nbdkit-python-plugin(3)>:
import nbdkit
nbdkit.shutdown()
nbdkit.disconnect(force)
In L<nbdkit-rust-plugin(3)>:
use nbdkit::*;
pub fn shutdown()
pub fn disconnect(force: bool)
In L<nbdkit-sh-plugin(3)>, there are various magic error codes that
can be returned to indicate that shutdown or disconnection is needed.
See that documentation for a full description.
=head1 HISTORY
C<nbdkit_shutdown> was added in nbdkit 1.20.
C<nbdkit_disconnect> was added in nbdkit 1.34.
=head1 SEE ALSO
L<nbdkit(1)>,
L<nbdkit-plugin(3)>,
L<nbdkit-filter(3)>.
=head1 AUTHORS
Eric Blake
Richard W.M. Jones
=head1 COPYRIGHT
Copyright Red Hat
|
