From 86f7473727ce6b9557e5f8c3f463929c2a896f59 Mon Sep 17 00:00:00 2001 From: Christien Rioux Date: Tue, 5 Mar 2024 19:26:23 -0500 Subject: [PATCH] clarify semantics --- veilid-core/proto/veilid.capnp | 4 ++-- veilid-core/proto/veilid_capnp.rs | 2 +- veilid-core/src/rpc_processor/rpc_watch_value.rs | 2 -- veilid-core/src/storage_manager/mod.rs | 3 +-- veilid-core/src/veilid_api/routing_context.rs | 5 ++++- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/veilid-core/proto/veilid.capnp b/veilid-core/proto/veilid.capnp index 1de1ec23..46dc4f33 100644 --- a/veilid-core/proto/veilid.capnp +++ b/veilid-core/proto/veilid.capnp @@ -353,7 +353,7 @@ struct OperationSetValueA @0x9378d0732dc95be2 { struct OperationWatchValueQ @0xf9a5a6c547b9b228 { key @0 :TypedKey; # key for value to watch - subkeys @1 :List(SubkeyRange); # subkey range to watch (up to 512 subranges), can not be empty, to watch everything use 0..=UINT32_MAX + subkeys @1 :List(SubkeyRange); # subkey range to watch (up to 512 subranges), if empty this implies 0..=UINT32_MAX expiration @2 :UInt64; # requested timestamp when this watch will expire in usec since epoch (can be return less, 0 for max) count @3 :UInt32; # requested number of changes to watch for (0 = cancel, 1 = single shot, 2+ = counter, UINT32_MAX = continuous) watchId @4 :UInt64; # if 0, request a new watch. if >0, existing watch id @@ -370,7 +370,7 @@ struct OperationWatchValueA @0xa726cab7064ba893 { struct OperationValueChanged @0xd1c59ebdd8cc1bf6 { key @0 :TypedKey; # key for value that changed - subkeys @1 :List(SubkeyRange); # subkey range that changed (up to 512 ranges at a time, this can be empty if this is a watch expiration notice) + subkeys @1 :List(SubkeyRange); # subkey range that changed (up to 512 ranges at a time, if empty this is a watch expiration notice) count @2 :UInt32; # remaining changes left (0 means watch has expired) watchId @3 :UInt64; # watch id this value change came from value @4 :SignedValueData; # first value that changed (the rest can be gotten with getvalue) diff --git a/veilid-core/proto/veilid_capnp.rs b/veilid-core/proto/veilid_capnp.rs index f844bc9a..5a390421 100644 --- a/veilid-core/proto/veilid_capnp.rs +++ b/veilid-core/proto/veilid_capnp.rs @@ -21406,4 +21406,4 @@ pub mod operation { } } -//BUILDHASH:2361d45ebb46feb1cecc71c1756fc90ff94487663e8d7211177e6df6e4033386 +//BUILDHASH:4ee16918900e322a0daa4bb0a11ca6094989c65936a653b0b78811e027d4d962 diff --git a/veilid-core/src/rpc_processor/rpc_watch_value.rs b/veilid-core/src/rpc_processor/rpc_watch_value.rs index a43f15b8..e01fd7b1 100644 --- a/veilid-core/src/rpc_processor/rpc_watch_value.rs +++ b/veilid-core/src/rpc_processor/rpc_watch_value.rs @@ -131,8 +131,6 @@ impl RPCProcessor { // Validate accepted requests if accepted { - xxx does this make sense? - // Verify returned answer watch id is the same as the question watch id if it exists if let Some(question_watch_id) = question_watch_id { if question_watch_id != watch_id { diff --git a/veilid-core/src/storage_manager/mod.rs b/veilid-core/src/storage_manager/mod.rs index 21dcc67b..7fae7899 100644 --- a/veilid-core/src/storage_manager/mod.rs +++ b/veilid-core/src/storage_manager/mod.rs @@ -566,8 +566,7 @@ impl StorageManager { Ok(None) } - /// Add or change an outbound watch to a DHT value - xxx decide if empty subkey range is valid. should probably reject that everywhere and use a default range of 'full' + /// Create,update or cancel an outbound watch to a DHT value pub async fn watch_values( &self, key: TypedKey, diff --git a/veilid-core/src/veilid_api/routing_context.rs b/veilid-core/src/veilid_api/routing_context.rs index 0a176186..eeba9db8 100644 --- a/veilid-core/src/veilid_api/routing_context.rs +++ b/veilid-core/src/veilid_api/routing_context.rs @@ -389,7 +389,10 @@ impl RoutingContext { /// Cancels a watch early /// - /// This is a convenience function that cancels watching all subkeys in a range + /// This is a convenience function that cancels watching all subkeys in a range. The subkeys specified here + /// are subtracted from the watched subkey range. If no range is specified, this is equivalent to cancelling the entire range of subkeys. + /// Only the subkey range is changed, the expiration and count remain the same. + /// If no subkeys remain, the watch is entirely cancelled and will receive no more updates. /// Returns Ok(true) if there is any remaining watch for this record /// Returns Ok(false) if the entire watch has been cancelled #[instrument(target = "veilid_api", level = "debug", ret, err)]