package async

You can search for identifiers within the package.

in-package search v0.2.0

package async

async
- Async
  - Command
  - Deferred
    
    Or_error
    
    Expect_test_config
    
    IO
  - Expect_test_config
    
    IO
  - Expect_test_config_or_error
    
    IO
  - Ppx_log_syntax
    
    Global
    
    No_global
    
    Ppx_log_syntax
    
    Global
  - Quickcheck
async.async_command
- Async_command
  - Staged
async.async_quickcheck
- Async_quickcheck
  - Configure
    
    Config
async.async_rpc
- Async_rpc
  - Rpc
    
    Connection
    
    Low_latency_transport
    
    Config
    
    Reader
    
    With_internal_reader
    
    With_internal_reader
    
    Writer
    
    Transport
    
    Reader
    
    Tcp
    
    Writer
async.lock_file_async
- Lock_file_async
  - Flock
  - Nfs
  - Symlink
async.log_extended
- Log_extended
  - Command
  - Console
    
    Blocking
  - Syslog
    
    Blocking
async.persistent_connection
- Persistent_connection
  - Make
    
    Conn
    
    Event
  - Rpc
    
    Event
  - S
    
    Event
  - S_rpc
    
    Event
  - Versioned_rpc
    
    Event
async.unpack_sequence
- Unpack_sequence

Legend:
Library
Module
Module type
Parameter
Class
Class type

include module type of struct include Async_command end

include module type of struct include Core.Command end

include module type of struct include Command end

module type Enumerable_sexpable = Async_command.Enumerable_sexpable

module type Enumerable_stringable = Async_command.Enumerable_stringable

module Auto_complete = Async_command.Auto_complete

Specifications for command-line auto-completion.

module Flag = Async_command.Flag

Command-line flag specifications.

module Anons = Async_command.Anons

Anonymous command-line argument specification.

type t = Async_command.t

Commands which can be combined into a hierarchy of subcommands.

type ('main, 'result) basic_spec_command =
  summary:Base.string ->
  ?readme:(Base.unit -> Base.string) ->
  ('main, Base.unit -> 'result) Async_command.Spec.t ->
  'main ->
  t

val basic_spec : ('main, Base.unit) basic_spec_command

basic_spec ~summary ?readme spec main is a basic command that executes a function main which is passed parameters parsed from the command line according to spec. summary is to contain a short one-line description of its behavior. readme is to contain any longer description of its behavior that will go on that command's help screen.

type 'result basic_command =
  summary:Base.string ->
  ?readme:(Base.unit -> Base.string) ->
  (Base.unit -> 'result) Async_command.Param.t ->
  t

val basic : Base.unit basic_command

Same general behavior as basic_spec, but takes a command line specification built up using Params instead of Spec.

val basic_or_error : Base.unit Base.Or_error.t basic_command

basic_or_error is like basic, 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 group : 
  summary:Base.string ->
  ?readme:(Base.unit -> Base.string) ->
  ?preserve_subcommand_order:Base.unit ->
  ?body:(path:Base.string Base.list -> Base.unit) ->
  (Base.string * t) Base.list ->
  t

group ~summary subcommand_alist is a compound command with named subcommands, as found in subcommand_alist. summary is to contain a short one-line description of the command group. readme is to contain any longer description of its behavior that will go on that command's help screen.

NOTE: subcommand names containing underscores will be rejected; use dashes instead.

body is called when no additional arguments are passed -- in particular, when no subcommand is passed. Its path argument is the subcommand path by which the group command was reached.

val lazy_group : 
  summary:Base.string ->
  ?readme:(Base.unit -> Base.string) ->
  ?preserve_subcommand_order:Base.unit ->
  ?body:(path:Base.string Base.list -> Base.unit) ->
  (Base.string * t) Base.list Base.Lazy.t ->
  t

lazy_group is the same as group, except that the list of subcommands may be generated lazily.

val exec : 
  summary:Base.string ->
  ?readme:(Base.unit -> Base.string) ->
  ?child_subcommand:Base.string Base.list ->
  ?env:
    [ `Replace of (Base.string * Base.string) Base.list
    | `Extend of (Base.string * Base.string) Base.list
    | `Override of (Base.string * Base.string Base.option) Base.list
    | `Replace_raw of Base.string Base.list ] ->
  path_to_exe:
    [ `Absolute of Base.string
    | `Relative_to_argv0 of Base.string
    | `Relative_to_me of Base.string ] ->
  Base.unit ->
  t

exec ~summary ~path_to_exe runs exec on the executable at path_to_exe. If path_to_exe is `Absolute path then path is executed without any further qualification. If it is `Relative_to_me path then Filename.dirname Sys.executable_name ^ "/" ^ path is executed instead. All of the usual caveats about Sys.executable_name apply: specifically, it may only return an absolute path in Linux. On other operating systems it will return Sys.argv.(0). If it is `Relative_to_argv0 path then Sys.argv.(0) ^ "/" ^ path is executed.

The child_subcommand argument allows referencing a subcommand one or more levels below the top-level of the child executable. It should not be used to pass flags or anonymous arguments to the child.

Care has been taken to support nesting multiple executables built with Command. In particular, recursive help and autocompletion should work as expected.

NOTE: Non-Command executables can be used with this function but will still be executed when help -recursive is called or autocompletion is attempted (despite the fact that neither will be particularly helpful in this case). This means that if you have a shell script called "reboot-everything.sh" that takes no arguments and reboots everything no matter how it is called, you shouldn't use it with exec.

Additionally, no loop detection is attempted, so if you nest an executable within itself, help -recursive and autocompletion will hang forever (although actually running the subcommand will work).

val of_lazy : t Base.Lazy.t -> t

of_lazy thunk constructs a lazy command that is forced only when necessary to run it or extract its shape.

val summary : t -> Base.string

Extracts the summary string for a command.

module Shape = Async_command.Shape

val exit : Base.int -> _

call this instead of Core.exit if in command-related code that you want to run in tests. For example, in the body of Command.Param.no_arg_abort

module Deprecated = Async_command.Deprecated

Deprecated should be used only by Deprecated_command. At some point it will go away.

Deprecated values that moved from Core.Command to Command_unix.

val run : [ `Use_Command_unix ]

deprecated [since 2021-03] Use [Command_unix]

module Path = Async_command.Path

val shape : [ `Use_Command_unix ]

deprecated [since 2021-03] Use [Command_unix]

module Arg_type = Async_command.Arg_type

module Param = Async_command.Param

module Spec = Async_command.Spec

module Let_syntax = Async_command.Let_syntax

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

val async : unit Async_kernel.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.

If behave_nicely_in_pipeline is true, then Writer.behave_nicely_in_pipeline () is called when the command starts. Its default is true.

val async_spec : 
  ('a, unit Async_kernel.Deferred.t) basic_spec_command with_options

val async_or_error : 
  unit Async_kernel.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_kernel.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 = Async_command.Staged

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