package console

  1. Overview
  2. Docs

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.

type t = Console__.Task_core.t

The type for tasks.

Sourcetype level = [
  1. | `App
  2. | `Error
  3. | `Warning
  4. | `Info
  5. | `Debug
]

The type for the levels of a line of output: those of Logs.

Sourcetype state = [
  1. | `Running
  2. | `Succeeded
  3. | `Failed
  4. | `Cancelled
]

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.

Sourcetype progress = [
  1. | `Spin
  2. | `Items of int * int
  3. | `Bytes of int64 * int64
]

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

Sourceval root : ?label:string -> now:(unit -> float) -> unit -> t

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.

Sourceval start : ?key:string -> ?log_lines:int -> ?transient:bool -> t -> string -> t

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 same key under the same root returns the same task, and its label, parent, log_lines and transient are ignored.
  • log_lines is how many of the task's latest lines its row shows under it while it runs (defaults to 8).
  • transient (defaults to false) 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, Logs messages 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.

val run : ?key:string -> ?log_lines:int -> ?transient:bool -> t -> string -> (t -> 'a) -> 'a

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) -> 'a

within 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 -> unit

set_label t label renames t. The root keeps its label.

val set_items : t -> count:int -> total:int -> unit

set_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 -> unit

set_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.

val log : ?level:level -> t -> string -> unit

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 log is dropped. A Logs message 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 -> unit

succeed 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.

val fail : ?message:string -> t -> unit

fail t is like succeed but ends t as a failure.

val cancel : ?message:string -> t -> unit

cancel t is like succeed but ends t as cancelled.

Accessors

val label : t -> string

label t is the label of t, as it shows: on one line, at most 4 KiB.

val parent : t -> t option

parent t is the task t was started under, None for a root.

Sourceval children : t -> t list

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 list

path t is the labels from the top task down to t, [] for a root.

val state : t -> state

state t is where t is.

Sourceval progress : t -> progress

progress t is how much of t is done.

val message : t -> string option

message t is the message t ended with, if any.

val elapsed : t -> float

elapsed t is the seconds t ran for, or has run for so far.

Sourceval rate : t -> float option

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.

Sourceval output : t -> string list

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 -> int

dropped t is the number of t's oldest lines that output no longer holds, to keep it within 1 MiB.

val pp : t Fmt.t

pp formats a task for diagnostics, in an unspecified format.

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.

Sourcemodule Event : sig ... end

JSON events.

val on_event : t -> (Event.t -> unit) -> unit

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.