Module `Async_command`

Async.Command is Core.Command with additional Async functions.

include module type of sig ... end

module Arg_type = Core__Command.Arg_type

module Flag = Core__Command.Flag

module Anons = Core__Command.Anons

module Param = Core__Command.Param

module Let_syntax = Core__Command.Let_syntax

module Spec = Core__Command.Spec

type t = Core_kernel__Command.t
type ('main, 'result) basic_spec_command = summary:Core_kernel__.Import.string -> ?⁠readme:(Core_kernel__.Import.unit -> Core_kernel__.Import.string) -> ('main, Core_kernel__.Import.unit -> 'result) Spec.t -> 'main -> t

val basic_spec : ('main, Core_kernel__.Import.unit) basic_spec_command

type 'result basic_command = summary:Core_kernel__.Import.string -> ?⁠readme:(Core_kernel__.Import.unit -> Core_kernel__.Import.string) -> (Core_kernel__.Import.unit -> 'result) Param.t -> t

val basic : Core_kernel__.Import.unit basic_command
val group : summary:Core_kernel__.Import.string -> ?⁠readme:(Core_kernel__.Import.unit -> Core_kernel__.Import.string) -> ?⁠preserve_subcommand_order:Core_kernel__.Import.unit -> ?⁠body:(path:Core_kernel__.Import.string Core_kernel__.Import.list -> Core_kernel__.Import.unit) -> (Core_kernel__.Import.string * t) Core_kernel__.Import.list -> t
val lazy_group : summary:Core_kernel__.Import.string -> ?⁠readme:(Core_kernel__.Import.unit -> Core_kernel__.Import.string) -> ?⁠preserve_subcommand_order:Core_kernel__.Import.unit -> ?⁠body:(path:Core_kernel__.Import.string Core_kernel__.Import.list -> Core_kernel__.Import.unit) -> (Core_kernel__.Import.string * t) Core_kernel__.Import.list Core_kernel.Lazy.t -> t
val exec : summary:Core_kernel__.Import.string -> ?⁠readme:(Core_kernel__.Import.unit -> Core_kernel__.Import.string) -> ?⁠child_subcommand:Core_kernel__.Import.string Core_kernel__.Import.list -> path_to_exe:[ `Absolute of Core_kernel__.Import.string | `Relative_to_argv0 of Core_kernel__.Import.string | `Relative_to_me of Core_kernel__.Import.string ] -> Core_kernel__.Import.unit -> t
val of_lazy : t Core_kernel.Lazy.t -> t
val summary : t -> Core_kernel__.Import.string
val exit : Core_kernel__.Import.int -> 'a

module Private = Core__Command.Private

val run : ?⁠verbose_on_parse_error:bool -> ?⁠version:string -> ?⁠build_info:string -> ?⁠argv:string list -> ?⁠extend:(string list -> string list) -> t -> unit

module Path = Core__Command.Path

module Shape = Core__Command.Shape

val shape : t -> Shape.t

module Deprecated = Core__Command.Deprecated

type 'a with_options = ?⁠extract_exn:bool -> 'a

val async : unit Async_command__.Import.Deferred.t basic_command with_options

async is like Core.Command.basic, except that the main function it expects returns unit Deferred.t, instead of unit. async will also start the Async scheduler before main is run, and will stop the scheduler when main returns.

async also handles top-level exceptions by wrapping the user-supplied function in a Monitor.try_with. If an exception is raised, it will print it to stderr and call shutdown 1. The extract_exn argument is passed along to Monitor.try_with; by default it is false.

val async_spec : ('a, unit Async_command__.Import.Deferred.t) basic_spec_command with_options
val async_or_error : unit Async_command__.Import.Deferred.Or_error.t basic_command with_options: async_or_error is like async, except that the main function it expects may return an error, in which case it prints out the error message and shuts down with exit code 1.

val async_spec_or_error : ('a, unit Async_command__.Import.Deferred.Or_error.t) basic_spec_command with_options

Staged functions allow the main function to be separated into two stages. The first part is guaranteed to run before the Async scheduler is started, and the second part will run after the scheduler is started. This is useful if the main function runs code that relies on the fact that threads have not been created yet (e.g., Daemon.daemonize).

As an example:

let main () =
  assert (not (Scheduler.is_running ()));
  stage (fun `Scheduler_started ->
    assert (Scheduler.is_running ());
    Deferred.unit
  )

type 'r staged = ([ `Scheduler_started ] -> 'r) Core.Staged.t

module Staged : sig ... end

To create an Arg_type.t that uses auto-completion and uses Async to compute the possible completions, one should use

Arg_type.create ~complete of_string

where complete wraps its Async operations in Thread_safe.block_on_async. With this, the complete function is only called when the executable is auto-completing, not for ordinary execution. This improves performance, and also means that the Async scheduler isn't started for ordinary execution of the command, which makes it possible for the command to daemonize (which requires the scheduler to not have been started).