|
| 1 | +/// A keyvalue interface that provides batch operations. |
| 2 | +/// |
| 3 | +/// A batch operation is an operation that operates on multiple keys at once. |
| 4 | +/// |
| 5 | +/// Batch operations are useful for reducing network round-trip time. For example, if you want to |
| 6 | +/// get the values associated with 100 keys, you can either do 100 get operations or you can do 1 |
| 7 | +/// batch get operation. The batch operation is faster because it only needs to make 1 network call |
| 8 | +/// instead of 100. |
| 9 | +/// |
| 10 | +/// A batch operation does not guarantee atomicity, meaning that if the batch operation fails, some |
| 11 | +/// of the keys may have been modified and some may not. |
| 12 | +/// |
| 13 | +/// This interface does has the same consistency guarantees as the `store` interface, meaning that |
| 14 | +/// you should be able to "read your writes." |
| 15 | +/// |
| 16 | +/// Please note that this interface is bare functions that take a reference to a bucket. This is to |
| 17 | +/// get around the current lack of a way to "extend" a resource with additional methods inside of |
| 18 | +/// wit. Future version of the interface will instead extend these methods on the base `bucket` |
| 19 | +/// resource. |
| 20 | +interface batch { |
| 21 | + use store.{bucket, error}; |
| 22 | + |
| 23 | + /// Get the key-value pairs associated with the keys in the store. It returns a list of |
| 24 | + /// key-value pairs. |
| 25 | + /// |
| 26 | + /// If any of the keys do not exist in the store, it returns a `none` value for that pair in the |
| 27 | + /// list. |
| 28 | + /// |
| 29 | + /// MAY show an out-of-date value if there are concurrent writes to the store. |
| 30 | + /// |
| 31 | + /// If any other error occurs, it returns an `Err(error)`. |
| 32 | + get-many: func(bucket: borrow<bucket>, keys: list<string>) -> result<list<option<tuple<string, list<u8>>>>, error>; |
| 33 | + |
| 34 | + /// Set the values associated with the keys in the store. If the key already exists in the |
| 35 | + /// store, it overwrites the value. |
| 36 | + /// |
| 37 | + /// Note that the key-value pairs are not guaranteed to be set in the order they are provided. |
| 38 | + /// |
| 39 | + /// If any of the keys do not exist in the store, it creates a new key-value pair. |
| 40 | + /// |
| 41 | + /// If any other error occurs, it returns an `Err(error)`. When an error occurs, it does not |
| 42 | + /// rollback the key-value pairs that were already set. Thus, this batch operation does not |
| 43 | + /// guarantee atomicity, implying that some key-value pairs could be set while others might |
| 44 | + /// fail. |
| 45 | + /// |
| 46 | + /// Other concurrent operations may also be able to see the partial results. |
| 47 | + set-many: func(bucket: borrow<bucket>, key-values: list<tuple<string, list<u8>>>) -> result<_, error>; |
| 48 | + |
| 49 | + /// Delete the key-value pairs associated with the keys in the store. |
| 50 | + /// |
| 51 | + /// Note that the key-value pairs are not guaranteed to be deleted in the order they are |
| 52 | + /// provided. |
| 53 | + /// |
| 54 | + /// If any of the keys do not exist in the store, it skips the key. |
| 55 | + /// |
| 56 | + /// If any other error occurs, it returns an `Err(error)`. When an error occurs, it does not |
| 57 | + /// rollback the key-value pairs that were already deleted. Thus, this batch operation does not |
| 58 | + /// guarantee atomicity, implying that some key-value pairs could be deleted while others might |
| 59 | + /// fail. |
| 60 | + /// |
| 61 | + /// Other concurrent operations may also be able to see the partial results. |
| 62 | + delete-many: func(bucket: borrow<bucket>, keys: list<string>) -> result<_, error>; |
| 63 | +} |
0 commit comments