package b0
-
b0.b00.kit
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
package b0
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
Build operations.
This module provides a type for specifying operations and their result. Operation execution and caching are respectively handled by the Exec and Reviver modules.
Operation status
type failure = | Exec of string option(*Execution failure with a potential error msg.
*)| Missing_writes of B0_std.Fpath.t list(*Write specification failure.
*)| Missing_reads of B0_std.Fpath.t list(*Read synchronisation failure.
*)
The type for operation failures.
type status = | Aborted(*Aborted due to prerequisite failure.
*)| Done(*Executed successfully.
*)| Failed of failure(*Executed unsuccessfully.
*)| Waiting(*Waiting for execution.
*)
The type for operation statuses.
Operations
The type for build operation marks. Marks have no special semantics they are just used to label operations for UI purposes.
type op = tAgain.
module Copy : sig ... endFile copy.
module Delete : sig ... endPath deletion.
module Mkdir : sig ... endDirectory creation.
module Notify : sig ... endEnd-user notifications.
module Read : sig ... endFile reads.
module Spawn : sig ... endTool spawns.
module Wait_files : sig ... endWaiting on files.
module Write : sig ... endFile writes.
val kind_name : kind -> stringkind_name k is an end user name for kind k.
val v :
id ->
mark:mark ->
time_created:B0_std.Mtime.span ->
time_started:B0_std.Mtime.span ->
duration:B0_std.Mtime.span ->
revived:bool ->
status:status ->
reads:B0_std.Fpath.t list ->
writes:B0_std.Fpath.t list ->
writes_manifest_root:B0_std.Fpath.t option ->
hash:B0_std.Hash.t ->
?post_exec:(op -> unit) ->
?k:(op -> unit) ->
kind ->
tv constructs an operation. See the corresponding accessors for the semantics of various arguments.
val mark : t -> stringmark o is the mark of o.
val time_created : t -> B0_std.Mtime.spantime_created o is o's creation time.
val time_started : t -> B0_std.Mtime.spantime_started o is o's execution start time. This is different from B0_std.Mtime.Span.max_span once the operation has been submitted for execution.
val time_ended : t -> B0_std.Mtime.spantime_ended o is o's execution end time. This is different from B0_std.Mtime.Span.max_span once the operation has been completed and collected.
val waited : t -> B0_std.Mtime.spanwaited is o's waiting time between creation and execution.
val duration : t -> B0_std.Mtime.spanduration is o's execution duration time.
val revived : t -> boolrevived o is true iff o was revived from a cache. Only relevant if hash is not B0_std.Hash.nil.
val reads : t -> B0_std.Fpath.t listreads o are the file paths read by the operation.
val writes : t -> B0_std.Fpath.t listwrites o are the file paths written by o.
val writes_manifest_root : t -> B0_std.Fpath.t optionwrites_manifest_root o if Some root, the operation is cached using a manifest key. This means the writes made relative to root are stored along-side the cache key.
val hash : t -> B0_std.Hash.thash o is the operation's hash. This is B0_std.Hash.nil before the operation hash has been effectively computed and set via set_hash. This remains B0_std.Hash.nil for operations that are not revivable.
Updating the build operation
val invoke_k : t -> unitexec_k o () invokes and discards o's continuation. Note that this does not protect against the continuation raising.
val discard_k : t -> unitdiscard o discards o's continuation.
val invoke_post_exec : t -> unitexec_post_exec o invokes and discards o's post execution hook. This hook called is right after the operation execution and, if applicable, before reviver recording. It is always called even if the operation fails or is revived (use status and revived to check these conditions). Note that if the hook unexpectedly raises this turns o in to a failure.
val discard_post_exec : t -> unitdiscard_post_exec o discards o's post execution hook.
val abort : t -> unitabort o sets the status of o to Op.status.Aborted and discards the operation closures (including kind specific ones).
val set_time_started : t -> B0_std.Mtime.span -> unitset_time_started o t sets o's execution start time to t.
val set_time_ended : t -> B0_std.Mtime.span -> unitset_time_ended o t sets o's execution end time to s.
val set_revived : t -> bool -> unitset_revived o b sets o's cache revival status to b.
set_status_from_result o r sets status of operation o to Executed if r is Ok _ and Failed (Exec e) if r is Error e.
val set_reads : t -> B0_std.Fpath.t list -> unitset_reads t fs sets the file paths read by o to fs. Note that this resets the hash.
val set_writes : t -> B0_std.Fpath.t list -> unitset_writes t fs sets the file paths written by o to fs.
val set_writes_manifest_root : t -> B0_std.Fpath.t option -> unitset_writes_manifest_root t r sets the writes manifest root to r.
val set_hash : t -> B0_std.Hash.t -> unitset_hash o h sets the operation hash to h.
Operation sets and map
Analyzing operations
val did_not_write : t -> B0_std.Fpath.t listdid_not_write o compares writes with the current state of the file system and reports those files that do not exist.
val cannot_read : t -> B0_std.Fpath.t listcannot_read o compares reads with the current state of the file system and reports those files that cannot be read.
val unready_reads :
ready_roots:B0_std.Fpath.Set.t ->
t list ->
B0_std.Fpath.Set.tunready_reads os are the file read by os that are not written by those and not in ready_roots.
val read_write_maps :
t list ->
Set.t B0_std.Fpath.Map.t * Set.t B0_std.Fpath.Map.tread_write_maps ops is reads, writes with reads mapping file paths to operations that reads them and writes mapping file paths to operations that write them.
val write_map : t list -> Set.t B0_std.Fpath.Map.twrite_map os is snd (read_write_maps os). If one of the operation sets in the map is not a singleton the operations should likely not be run toghether.
find_read_write_cycle os is Some cs if there exists a read/write cycle among the operations os. This means each each element of cs writes a file read by its successor in the list with the successor of the last element being the first.
type aggregate_error = | Failures(*Some operations failed.
*)| Cycle of t list(*Dependency cycle.
*)| Never_became_ready of B0_std.Fpath.Set.t(*Some files never became ready.
*)
The type for errors related to a list of operations. This is:
Failures, if there is one or more operations in the list thatFailed.Cycle ops, if there is a set ofWaitingoperations in the list whose individual reads and writes leads to a dependency cycle. See alsofind_read_write_cycle.Never_became_ready fs, withfsfiles that are in the reads ofWaitingoperations but are written by no operation from the list and were not made ready.
Note that formally more than one of these conditions can be true at the same time. But Never_became_ready is only reported once the first two kind of errors have been ruled out. The reason is that those files that never became ready may be created by continuations of the failed or cyclic operations and reporting them would not lead the user to focus on the right cause.
val find_aggregate_error :
ready_roots:B0_std.Fpath.Set.t ->
t list ->
(unit, aggregate_error) resultfind_aggregate_error ~ready_roots os finds an aggregate error among the list of operation os, assuming files ready_roots were made ready. This is Ok () if all operations os B000.Op.status.Done.