Verified Commit 8e53ccb1 authored by Philippe B.'s avatar Philippe B. 🏂

Shell/DDb: cache -> requester

Cache was found generic/misleading. We use Requester instead,
and rephrased `cache.mli` introductory documentation (+ fix typos).

lib_cache -> lib_requester
Cache -> Requester
CACHE -> REQUESTER
parent 145641cf
......@@ -1059,15 +1059,15 @@ opam:tezos-protocol-005-PsBabyM1-parameters:
variables:
package: tezos-protocol-005-PsBabyM1-parameters
opam:tezos-endorser-alpha-commands:
opam:tezos-requester:
<<: *opam_definition
variables:
package: tezos-endorser-alpha-commands
package: tezos-requester
opam:tezos-cache:
opam:tezos-endorser-alpha-commands:
<<: *opam_definition
variables:
package: tezos-cache
package: tezos-endorser-alpha-commands
opam:tezos-client:
<<: *opam_definition
......
(library
(name tezos_cache)
(public_name tezos-cache)
(name tezos_requester)
(public_name tezos-requester)
(libraries tezos-base
tezos-stdlib-unix
tezos-shell-services)
......
......@@ -23,7 +23,7 @@
(* *)
(*****************************************************************************)
module type CACHE = sig
module type REQUESTER = sig
type t
type key
......@@ -55,8 +55,8 @@ module type CACHE = sig
val clear_or_cancel : t -> key -> unit
end
module type FULL_CACHE = sig
include CACHE
module type FULL_REQUESTER = sig
include REQUESTER
type store
......@@ -171,8 +171,8 @@ module type REQUEST = sig
val send : param -> P2p_peer.Id.t -> key list -> unit
end
(** The cache uses a generic scheduler to schedule its requests.
The [Memory_table] must be shared between the scheduler and the cache
(** The requester uses a generic scheduler to schedule its requests.
The [Memory_table] must be shared between the scheduler and the requester
as it used to store both pending requests and found values. *)
module Make_request_scheduler (Hash : sig
......@@ -189,7 +189,7 @@ end)
include SCHEDULER with type key := Hash.t and type param := Request.param
end = struct
include Internal_event.Legacy_logging.Make_semantic (struct
let name = "node.cache.scheduler." ^ Hash.name
let name = "node.requester.scheduler." ^ Hash.name
end)
type key = Hash.t
......@@ -499,7 +499,7 @@ end)
(Request : REQUEST with type key := Hash.t)
(Precheck : PRECHECK with type key := Hash.t and type value := Disk_table.value) : sig
include
FULL_CACHE
FULL_REQUESTER
with type key = Hash.t
and type value = Disk_table.value
and type param = Precheck.param
......@@ -566,9 +566,9 @@ end = struct
(* Missing data key *)
register_error_kind
`Permanent
~id:("cache." ^ Hash.name ^ ".missing")
~id:("requester." ^ Hash.name ^ ".missing")
~title:("Missing " ^ Hash.name)
~description:("Some " ^ Hash.name ^ " is missing from the cache")
~description:("Some " ^ Hash.name ^ " is missing from the requester")
~pp:(fun ppf key ->
Format.fprintf ppf "Missing %s %a" Hash.name Hash.pp key)
(Data_encoding.obj1 (Data_encoding.req "key" Hash.encoding))
......@@ -579,7 +579,7 @@ end = struct
`Permanent
~title:("Canceled fetch of a " ^ Hash.name)
~description:("The fetch of a " ^ Hash.name ^ " has been canceled")
~id:("cache." ^ Hash.name ^ ".fetch_canceled")
~id:("requester." ^ Hash.name ^ ".fetch_canceled")
~pp:(fun ppf key ->
Format.fprintf ppf "Fetch of %s %a canceled" Hash.name Hash.pp key)
Data_encoding.(obj1 (req "key" Hash.encoding))
......@@ -590,7 +590,7 @@ end = struct
`Permanent
~title:("Timed out fetch of a " ^ Hash.name)
~description:("The fetch of a " ^ Hash.name ^ " has timed out")
~id:("cache." ^ Hash.name ^ ".fetch_timeout")
~id:("requester." ^ Hash.name ^ ".fetch_timeout")
~pp:(fun ppf key ->
Format.fprintf ppf "Fetch of %s %a timed out" Hash.name Hash.pp key)
Data_encoding.(obj1 (req "key" Hash.encoding))
......
......@@ -23,31 +23,43 @@
(* *)
(*****************************************************************************)
(** Generic cache / request scheduling service.
(** Generic resource fetching/requesting service.
This module defines a generic key-value cache service [Cache].
This module defines a generic resource fetching service [Requester].
It is parameterized by abstract services [Disk], [Request], [Memory_table]
and [Precheck].
Values are looked up in [Disk.store] and are cached in [Memory_table.t].
It offers a key/value store interface. Values are looked up successively
in [Memory_table.t], then in [Disk.store]. If not found, they are
*requested* using the [Request] service. Ultimately, values are *cached* in
the [Memory_table] for faster retrieval on subsequent queries. This is
similar to a *read-through* cache except that values are never evicted
from the [Memory_table].
Internally, the service schedules requests to an abstract external
sources (e.g. network) for missing keys. The key is then *pending* and
while the caller waits the value to be available.
source (e.g. network) for missing keys. The key is then *pending*
and the caller waits for the value to be available.
When a value is missing, the cache sends a request via
[Request.send] to query a value to the network, but it is the
responsibility of the client to *notify* the cache with
[Cache.notify] when the requested value is available.
When a value is missing, the requester sends a request via
[Request.send] to query a value to the network. The requester must be
*notified* by an external component when the requested value is available
using [Requester.notify].
Notified values are validated before being inserted in the cache,
Notified values are validated before being inserted in the requester,
using the [Precheck] module.
The cache service offers two interfaces. [FULL_CACHE] is the full view, which
includes the creation, shutdown, and reception notification functions.
[CACHE] is a restricted view which essentially offers a *read-through*
cache interface. *)
The full resource fetching service is realized by the conjunction of
two components. The requester component, defined by this library, and
a notifying component (for instance, a worker thread waiting for network
messages).
The requester offers two interfaces. [FULL_REQUESTER] is the full
view, which includes the creation, shutdown, and notification
functions. It is to be used by the controller setting up the service,
and the notifying component. [REQUESTER] is the restricted view, exported
to the service final user. *)
module type CACHE = sig
module type REQUESTER = sig
type t
(** The index key *)
......@@ -83,8 +95,8 @@ module type CACHE = sig
The key is first looked up in memory, then on disk. If not present and
not already requested, it schedules a request, and blocks until
the cache is notified with [notify]. [param] is used to validate the
notified value once it is received. (see also [PRECHECK] and [notify].
the requester is notified with [notify]. [param] is used to validate the
notified value once it is received. (see also [PRECHECK] and [notify]).
Requests are re-sent via a 1.5 exponential back-off, with initial
delay set to [Request.initial_delay]. If the function
......@@ -105,8 +117,8 @@ module type CACHE = sig
val clear_or_cancel : t -> key -> unit
end
module type FULL_CACHE = sig
include CACHE
module type FULL_REQUESTER = sig
include REQUESTER
(** The "disk" storage *)
type store
......@@ -114,7 +126,7 @@ module type FULL_CACHE = sig
(** Configuration parameter to the [Request] service *)
type request_param
(** type of values notified to the cache *)
(** type of values notified to the requester *)
type notified_value
(** [pending t k] returns [true] iff the key status is pending *)
......@@ -124,13 +136,13 @@ module type FULL_CACHE = sig
once. *)
val watch : t -> (key * value) Lwt_stream.t * Lwt_watcher.stopper
(** [inject t k v] returns [false] if [k] is already present in the memory table
or in the disk, or has already been request. Otherwise it updates the
memory table and return [true] *)
(** [inject t k v] returns [false] if [k] is already present in the memory
table or in the disk, or has already been requested. Otherwise it
updates the memory table and return [true] *)
val inject : t -> key -> value -> bool Lwt.t
(** [notify t peer k nv] notifies the cache that a value has been received
for key [k], from peer [peer]. [nv] is a *notified value*. The
(** [notify t peer k nv] notifies the requester that a value has been
received for key [k], from peer [peer]. [nv] is a *notified value*. The
notified value is validated using [Precheck.precheck], and the
[param] provided at fetching time (see [PRECHECK]). If valid,
the memory table is updated and all promises waiting on this key are
......@@ -146,7 +158,7 @@ module type FULL_CACHE = sig
(** Returns the number of requests currently pending *)
val pending_requests : t -> int
(** [create ?global_input r s] creates a cache. [r] is the
(** [create ?global_input r s] creates a requester. [r] is the
configuration parameter passed to [Request] functions. *)
val create :
?global_input:(key * value) Lwt_watcher.input ->
......@@ -194,7 +206,7 @@ module type MEMORY_TABLE = sig
val length : 'a t -> int
end
(** [Requests] abstracts a service used to sends asynchronous key requests
(** [Requests] abstracts a service used to send asynchronous key requests
to peers. *)
module type REQUEST = sig
type key
......@@ -202,7 +214,7 @@ module type REQUEST = sig
(** [param] represents the state/configuration of the service. *)
type param
(** [initial_delay] is a service configuration time constant. Typically, use
(** [initial_delay] is a service configuration time constant. Typically, used
to set up a retry time interval. *)
val initial_delay : Time.System.Span.t
......@@ -254,7 +266,7 @@ end)
(Request : REQUEST with type key := Hash.t)
(Precheck : PRECHECK with type key := Hash.t and type value := Disk_table.value) : sig
include
FULL_CACHE
FULL_REQUESTER
with type key = Hash.t
and type value = Disk_table.value
and type param = Precheck.param
......
......@@ -16,4 +16,4 @@ build: [
["dune" "build" "-p" name "-j" jobs]
["dune" "runtest" "-p" name "-j" jobs] {with-test}
]
synopsis: "Tezos: generic request scheduler/cache service"
synopsis: "Tezos: generic resource fetching service"
......@@ -55,8 +55,8 @@ module Make_raw (Hash : sig
val tag : t Tag.def
end
end)
(Disk_table : Cache.DISK_TABLE with type key := Hash.t)
(Memory_table : Cache.MEMORY_TABLE with type key := Hash.t)
(Disk_table : Requester.DISK_TABLE with type key := Hash.t)
(Memory_table : Requester.MEMORY_TABLE with type key := Hash.t)
(Request_message : sig
type param
......@@ -66,7 +66,7 @@ end)
val forge : param -> Hash.t list -> Message.t
end)
(Precheck : Cache.PRECHECK
(Precheck : Requester.PRECHECK
with type key := Hash.t
and type value := Disk_table.value) =
struct
......@@ -107,7 +107,7 @@ struct
end
module Table =
Cache.Make (Hash) (Disk_table) (Memory_table) (Request) (Precheck)
Requester.Make (Hash) (Disk_table) (Memory_table) (Request) (Precheck)
type t = Table.t
......@@ -123,7 +123,7 @@ struct
Table.create ?global_input request_param disk
let shutdown t =
Logging.lwt_log_notice "Shutting down the cache..."
Logging.lwt_log_notice "Shutting down the requester..."
>>= fun () -> Table.shutdown t
end
......@@ -1071,7 +1071,7 @@ let watch_operation {operation_input; _} =
Lwt_watcher.create_stream operation_input
module Make
(Table : Cache.CACHE) (Kind : sig
(Table : Requester.REQUESTER) (Kind : sig
type t
val proj : t -> Table.t
......@@ -1109,7 +1109,7 @@ module Block_header = struct
let proj chain = chain.block_header_db
end) :
Cache.CACHE
Requester.REQUESTER
with type t := chain_db
and type key := Block_hash.t
and type value := Block_header.t
......@@ -1145,7 +1145,7 @@ module Operation = struct
let proj chain = chain.operation_db
end) :
Cache.CACHE
Requester.REQUESTER
with type t := chain_db
and type key := Operation_hash.t
and type value := Operation.t
......@@ -1163,7 +1163,7 @@ module Protocol = struct
let proj db = db.protocol_db
end) :
Cache.CACHE
Requester.REQUESTER
with type t := db
and type key := Protocol_hash.t
and type value := Protocol.t
......
......@@ -123,7 +123,7 @@ module Block_header : sig
type t = Block_header.t (* avoid shadowing. *)
include
Cache.CACHE
Requester.REQUESTER
with type t := chain_db
and type key := Block_hash.t
and type value := Block_header.t
......@@ -136,7 +136,7 @@ val read_block_header :
(** Index of all the operations of a given block (per validation pass). *)
module Operations :
Cache.CACHE
Requester.REQUESTER
with type t := chain_db
and type key = Block_hash.t * int
and type value = Operation.t list
......@@ -145,7 +145,7 @@ module Operations :
(** Index of all the hashes of operations of a given block (per
validation pass). *)
module Operation_hashes :
Cache.CACHE
Requester.REQUESTER
with type t := chain_db
and type key = Block_hash.t * int
and type value = Operation_hash.t list
......@@ -182,7 +182,7 @@ module Operation : sig
type t = Operation.t (* avoid shadowing. *)
include
Cache.CACHE
Requester.REQUESTER
with type t := chain_db
and type key := Operation_hash.t
and type value := Operation.t
......@@ -204,7 +204,7 @@ module Protocol : sig
type t = Protocol.t (* avoid shadowing. *)
include
Cache.CACHE
Requester.REQUESTER
with type t := db
and type key := Protocol_hash.t
and type value := Protocol.t
......
......@@ -10,7 +10,7 @@
tezos-shell-services
tezos-protocol-updater
tezos-validation
tezos-cache)
tezos-requester)
(flags (:standard -open Tezos_base__TzPervasives
-open Tezos_storage
-open Tezos_shell_context
......@@ -19,7 +19,7 @@
-open Tezos_shell_services
-open Tezos_protocol_updater
-open Tezos_validation
-open Tezos_cache)))
-open Tezos_requester)))
(alias
(name runtest_lint)
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment