package console
Module Console.TaskSource
The work a program reports: tasks under a root, with no drawing.
Tasks: the work a program reports, with no drawing.
A task has a label, a count of items or bytes, lines of output and an end. Tasks form a tree under a root, the work as a whole, and ending the root says how the work ended. Progress shows the tasks of a root as rows, lines, failures alone or JSON, and Console_eio.run makes a root, shows it and passes it to the program:
let build root =
Console.Task.run root "compile" (fun step ->
Console.Task.set_items step ~count:1 ~total:2;
Console.Task.log step "ocamlopt parser.ml";
Console.Task.set_items step ~count:2 ~total:2)A task belongs to the domain that runs its root, so call its functions from that domain alone. A task that ended ignores what it is told, and a line given to it with log is dropped; the root alone takes log after it ended, as output of no task.
The type for the levels of a line of output: those of Logs.
The type for where a task is: running, or how it ended. A task that ended has the Event.status of the same name in its "end" event, and the Theme.mark of the same name on its line.
The type for how much of a task is done: not said yet, so its row shows a spinner, or a count of items or of bytes done out of a total.
Roots and tasks
root ~now () is the work as a whole, timed by the clock now, in seconds. label, if given, names the work on the summary line (Progress.summary). A root is a task: it is current where no other is, its output is the output of no task, and ending it ends the work.
start parent label starts a task named label (a line feed in it is a space) under parent: a root, or a task.
key, if given, names the task. While it runs, a later call with the samekeyunder the same root returns the same task, and itslabel,parent,log_linesandtransientare ignored.log_linesis how many of the task's latest lines its row shows under it while it runs (defaults to8).transient(defaults tofalse) makes a task that shows only while it runs, and leaves neither a line of its own nor any of its output when it succeeds. Its output is all that is printed while it is current,Logsmessages included, so a line that should stay is printed outside it, or after it ended. One that fails or is cancelled shows as any other task does.
A task started under a task that ended, the root included, takes its ending at once.
run parent label f is f task, for a task started as start starts it and current while f runs (within). The task succeeds when f returns and fails when f raises, with the message label ^ ": " ^ Printexc.to_string e for the exception e (fail), which is raised again; but if f ended the task itself, that ending counts. Under Console_eio.run, a cancelled fiber cancels the task instead of failing it.
When key names a task that runs, run is within task (fun () -> f task) for that task. It ends nothing, and the task ends as the call that started it says.
val within : t -> (unit -> 'a) -> 'awithin t f is f () with t current while f runs and, under Console_eio.run, in the fibers f starts. The current task decides only where output goes: what f prints, and its Logs messages, are t's output. Where run starts a task, within enters one that exists, so it ends nothing, even when f raises.
Changes
val set_label : t -> string -> unitset_label t label renames t. The root keeps its label.
val set_items : t -> count:int -> total:int -> unitset_items t ~count ~total says that count items of total are done. A count never goes back: a smaller count or total than before is ignored, and a count above total raises the total.
The root counts nothing, as its summary line counts its tasks (Progress.summary): a count of the whole work is that of a task started for it. So a library that a nested Console_eio.run gives the root counts as it would under any task.
val set_bytes : t -> count:int64 -> total:int64 -> unitset_bytes t ~count ~total is like set_items for a task that counts bytes, whose row also shows the bytes per second. The root counts nothing.
log t text gives each line of text to t as its output, at level for a Logs message (by default, a line the program printed). It is the one-line form of within, for code where t is not current.
- A tab goes to the next stop of eight columns from the start of its line.
- A running task keeps its latest lines, which its row shows, and up to 1 MiB of all of them for its failure: past that, the oldest go first and a line counts them. A line, a label and a message are each kept up to 4 KiB, cut between two characters and ended with three dots.
- The output of the root is the output of no task.
- A line given to a task that ended with
logis dropped. ALogsmessage or a printed line from a fiber whose task ended is not: it goes to the scrollback at once, as that task's (Design).
val succeed : ?message:string -> t -> unitsucceed t ends t as a success, with message in place of its label if given. A task ends once: the first of succeed, fail and cancel counts, and the others do nothing. A task's ending is what the program says of it: a task that failed under t does not fail it.
The tasks under t that still run end first, in the order they started: they succeed with it, and are cancelled when it fails or is cancelled. On the root, this says how the work ended.
Accessors
val label : t -> stringlabel t is the label of t, as it shows: on one line, at most 4 KiB.
children t are the tasks under t, in the order they started: those that run, and those that ended and are still shown (Progress). A transient task that succeeded is not among them: the tasks under it take its place, as in Progress.tree.
val path : t -> string listpath t is the labels from the top task down to t, [] for a root.
val message : t -> string optionmessage t is the message t ended with, if any.
val elapsed : t -> floatelapsed t is the seconds t ran for, or has run for so far.
rate t is the items or bytes per second that t counts, as Progress.Layout.rate shows it, once a count was said after t started: it weighs the past by exp (-dt /. 2.) for dt seconds ago, so it depends on the time, not on how often the count is said. It is None before, and while nothing was counted.
output t is the lines of output t keeps, oldest first, each as log keeps it, the latest within 1 MiB. A task that failed or was cancelled keeps them until Progress printed it: as its top task moves to the scrollback, or as it ends without a terminal (Design). A task that succeeded keeps them only while it ends, for Progress.show's commit to draw. The root has none (log). The last log_lines of them (start) are those its row shows.
val dropped : t -> intdropped t is the number of t's oldest lines that output no longer holds, to keep it within 1 MiB.
JSON events
Each change of a task is an event, which on_event gives a program and which `Json (Progress) writes as one JSON object on a line of its own, in the order the events happen: the line is the Event.to_string of an Event.t, and Event.jsont reads it back. The summary line is not an event.
Objects may gain members, new events may be added, and a member whose values are listed may gain values, but the members of Event keep their meaning. A consumer skips a member, an event or a value it does not know, as Event.jsont does. An event of another name may give a listed member another type: Event.jsont then skips it too.
on_event t f calls f with each event of the work of t, every task under its root and the root itself, in the order they happen, from now on. f runs where the change is made, and must not change a task. A program writes its own lines from them, as `Json writes the JSON objects.