3:44 a.m.
Add two new fields, `cblifetime` and `cbcount`, to the `closure` type
in generator/API.ml*. `cblifetime` tells if the closure may only be used
for as long as the command is in flight or if the closure may be used
until the handle is destructed. `cbcount` tells whether the closure may
be called many times or just once.
This information is needed in the Rust bindings for:
a) Knowing if the closure trait should be `FnMut` or `FnOnce`
(see <https://doc.rust-lang.org/std/ops/trait.FnOnce.html>).
b) Knowing for what lifetime the closure should be valid. A closure that
may be called after the function invokation has returned must live
for the `'static` lietime. But static closures are inconveniant for
the user since they can't effectively borrow any local data. So it is
good if this restriction is relaxed when it is not needed.
---
generator/API.ml | 20 ++++++++++++++++++++
generator/API.mli | 17 +++++++++++++++++
2 files changed, 37 insertions(+)
diff --git a/generator/API.ml b/generator/API.ml
index f90a6fa..42b9eec 100644
--- a/generator/API.ml
+++ b/generator/API.ml
@@ -77,6 +77,8 @@ and ret =
and closure = {
cbname : string;
cbargs : cbarg list;
+ cblifetime : cblifetime;
+ cbcount : cbcount
}
and cbarg =
| CBArrayAndLen of arg * string
@@ -87,6 +89,12 @@ and cbarg =
| CBString of string
| CBUInt of string
| CBUInt64 of string
+and cblifetime =
+| CBCommand
+| CBHandle
+and cbcount =
+| CBOnce
+| CBMany
and enum = {
enum_prefix : string;
enums : (string * int) list
@@ -141,20 +149,28 @@ the handle from the NBD protocol handshake."
(* Closures. *)
let chunk_closure = {
cbname = "chunk";
+ cblifetime = CBCommand;
+ cbcount = CBMany;
cbargs = [ CBBytesIn ("subbuf", "count");
CBUInt64 "offset"; CBUInt "status";
CBMutable (Int "error") ]
}
let completion_closure = {
cbname = "completion";
+ cblifetime = CBCommand;
+ cbcount = CBOnce;
cbargs = [ CBMutable (Int "error") ]
}
let debug_closure = {
cbname = "debug";
+ cblifetime = CBHandle;
+ cbcount = CBMany;
cbargs = [ CBString "context"; CBString "msg" ]
}
let extent_closure = {
cbname = "extent";
+ cblifetime = CBCommand;
+ cbcount = CBMany;
cbargs = [ CBString "metacontext";
CBUInt64 "offset";
CBArrayAndLen (UInt32 "entries",
@@ -163,10 +179,14 @@ let extent_closure = {
}
let list_closure = {
cbname = "list";
+ cblifetime = CBCommand;
+ cbcount = CBMany;
cbargs = [ CBString "name"; CBString "description" ]
}
let context_closure = {
cbname = "context";
+ cblifetime = CBCommand;
+ cbcount = CBMany;
cbargs = [ CBString "name" ]
}
let all_closures = [ chunk_closure; completion_closure;
diff --git a/generator/API.mli b/generator/API.mli
index 361132d..ff85849 100644
--- a/generator/API.mli
+++ b/generator/API.mli
@@ -94,6 +94,12 @@ and ret =
and closure = {
cbname : string; (** name of callback function *)
cbargs : cbarg list; (** all closures return int for now *)
+ (** An upper bound of the lifetime of the closure. Either it will be used for
+ as long as the command is in flight or it may be used until the handle
+ is destructed. *)
+ cblifetime : cblifetime;
+ (** Whether the callback may only be called once or many times. *)
+ cbcount : cbcount;
}
and cbarg =
| CBArrayAndLen of arg * string (** array + number of entries *)
@@ -104,6 +110,17 @@ and cbarg =
| CBString of string (** like String *)
| CBUInt of string (** like UInt *)
| CBUInt64 of string (** like UInt64 *)
+and cblifetime =
+| CBCommand (** The closure may only be used until the command is retired.
+ (E.G., completion callback or list callback.) *)
+| CBHandle (** The closure might be used until the handle is descructed.
+ (E.G., debug callback.) *)
+and cbcount =
+| CBOnce (** The closure will be used 0 or 1 time if the aio_* call returned an
+ error and exactly once if the call succeeded.
+ (E.g., completion callback.) *)
+| CBMany (** The closure may be used any number of times.
+ (E.g., list callback.) *)
and enum = {
enum_prefix : string; (** prefix of each enum variant *)
enums : (string * int) list (** enum names and their values in C *)
--
2.41.0