# [Delimited Files](#Delimited-Files)
If `quotes` is `true`, columns enclosed within double-quote (") characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. Specifying `dims` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. If `comments` is `true`, lines beginning with `comment_char` and text following `comment_char` in any line are ignored.
**Examples**
```julia-repl
julia> using DelimitedFiles

julia> x = [1; 2; 3; 4];

julia> y = [5; 6; 7; 8];

julia> open("delim_file.txt", "w") do io
           writedlm(io, [x y])
       end

julia> readdlm("delim_file.txt", '\t', Int, '\n')
4×2 Matrix{Int64}:
 1  5
 2  6
 3  7
 4  8

julia> rm("delim_file.txt")
```
```julia
readdlm(source, delim::AbstractChar, eol::AbstractChar; options...)
```
If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a heterogeneous array of numbers and strings is returned.
```julia
readdlm(source, delim::AbstractChar, T::Type; options...)
```
The end of line delimiter is taken as `\n`.
**Examples**
```julia-repl
julia> using DelimitedFiles

julia> x = [1; 2; 3; 4];

julia> y = [1.1; 2.2; 3.3; 4.4];

julia> open("delim_file.txt", "w") do io
           writedlm(io, [x y], ',')
       end;

julia> readdlm("delim_file.txt", ',', Float64)
4×2 Matrix{Float64}:
 1.0  1.1
 2.0  2.2
 3.0  3.3
 4.0  4.4

julia> rm("delim_file.txt")
```
```julia
readdlm(source, delim::AbstractChar; options...)
```


# [Delimited Files](#Delimited-Files)
The end of line delimiter is taken as `\n`. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a heterogeneous array of numbers and strings is returned.
**Examples**
```julia-repl
julia> using DelimitedFiles

julia> x = [1; 2; 3; 4];

julia> y = [1.1; 2.2; 3.3; 4.4];

julia> open("delim_file.txt", "w") do io
           writedlm(io, [x y], ',')
       end;

julia> readdlm("delim_file.txt", ',')
4×2 Matrix{Float64}:
 1.0  1.1
 2.0  2.2
 3.0  3.3
 4.0  4.4

julia> z = ["a"; "b"; "c"; "d"];

julia> open("delim_file.txt", "w") do io
           writedlm(io, [x z], ',')
       end;

julia> readdlm("delim_file.txt", ',')
4×2 Matrix{Any}:
 1  "a"
 2  "b"
 3  "c"
 4  "d"

julia> rm("delim_file.txt")
```
```julia
readdlm(source, T::Type; options...)
```
The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as `\n`.
**Examples**
```julia-repl
julia> using DelimitedFiles

julia> x = [1; 2; 3; 4];

julia> y = [5; 6; 7; 8];

julia> open("delim_file.txt", "w") do io
           writedlm(io, [x y])
       end;

julia> readdlm("delim_file.txt", Int64)
4×2 Matrix{Int64}:
 1  5
 2  6
 3  7
 4  8

julia> readdlm("delim_file.txt", Float64)
4×2 Matrix{Float64}:
 1.0  5.0
 2.0  6.0
 3.0  7.0
 4.0  8.0

julia> rm("delim_file.txt")
```
```julia
readdlm(source; options...)
```


# [Delimited Files](#Delimited-Files)
The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as `\n`. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a heterogeneous array of numbers and strings is returned.
**Examples**
```julia-repl
julia> using DelimitedFiles

julia> x = [1; 2; 3; 4];

julia> y = ["a"; "b"; "c"; "d"];

julia> open("delim_file.txt", "w") do io
           writedlm(io, [x y])
       end;

julia> readdlm("delim_file.txt")
4×2 Matrix{Any}:
 1  "a"
 2  "b"
 3  "c"
 4  "d"

julia> rm("delim_file.txt")
```
```julia
writedlm(f, A, delim='\t'; opts)
```
Write `A` (a vector, matrix, or an iterable collection of iterable rows) as text to `f` (either a filename string or an `IO` stream) using the given delimiter `delim` (which defaults to tab, but can be any printable Julia object, typically a `Char` or `AbstractString`).
For example, two vectors `x` and `y` of the same length can be written as two columns of tab-delimited text to `f` by either `writedlm(f, [x y])` or by `writedlm(f, zip(x, y))`.
**Examples**
```julia-repl
julia> using DelimitedFiles

julia> x = [1; 2; 3; 4];

julia> y = [5; 6; 7; 8];

julia> open("delim_file.txt", "w") do io
           writedlm(io, [x y])
       end

julia> readdlm("delim_file.txt", '\t', Int, '\n')
4×2 Matrix{Int64}:
 1  5
 2  6
 3  7
 4  8

julia> rm("delim_file.txt")
```
------------------------------------------------------------------------


# Distributed Computing · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/Distributed/


# [Distributed Computing](#man-distributed)
Tools for distributed parallel processing.
```julia
addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers
```
Launches worker processes via the specified cluster manager.
For example, Beowulf clusters are supported via a custom cluster manager implemented in the package `ClusterManagers.jl`.
The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable `JULIA_WORKER_TIMEOUT` in the worker process's environment. Relevant only when using TCP/IP as transport.
To launch workers without blocking the REPL, or the containing function if launching workers programmatically, execute `addprocs` in its own task.
**Examples**
```julia
# On busy clusters, call `addprocs` asynchronously
t = @async addprocs(...)
```
```julia
# Utilize workers as and when they come online
if nprocs() > 1   # Ensure at least one new worker is available
   ....   # perform distributed execution
end
```
```julia
# Retrieve newly launched worker IDs, or any error messages
if istaskdone(t)   # Check if `addprocs` has completed to ensure `fetch` doesn't block
    if nworkers() == N
        new_pids = fetch(t)
    else
        fetch(t)
    end
end
```
```julia
addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, kwargs...) -> List of process identifiers
```


# [Distributed Computing](#man-distributed)
Add worker processes on remote machines via SSH. Configuration is done with keyword arguments (see below). In particular, the `exename` keyword can be used to specify the path to the `julia` binary on the remote machine(s).
`machines` is a vector of "machine specifications" which are given as strings of the form `[user@]host[:port] [bind_addr[:port]]`. `user` defaults to current user and `port` to the standard SSH port. If `[bind_addr[:port]]` is specified, other workers will connect to this worker at the specified `bind_addr` and `port`.
It is possible to launch multiple processes on a remote host by using a tuple in the `machines` vector or the form `(machine_spec, count)`, where `count` is the number of workers to be launched on the specified host. Passing `:auto` as the worker count will launch as many workers as the number of CPU threads on the remote host.
**Examples**:
```julia
addprocs([
    "remote1",               # one worker on 'remote1' logging in with the current username
    "user@remote2",          # one worker on 'remote2' logging in with the 'user' username
    "user@remote3:2222",     # specifying SSH port to '2222' for 'remote3'
    ("user@remote4", 4),     # launch 4 workers on 'remote4'
    ("user@remote5", :auto), # launch as many workers as CPU threads on 'remote5'
])
```
**Keyword arguments**:
-   `tunnel`: if `true` then SSH tunneling will be used to connect to the worker from the master process. Default is `false`.


# [Distributed Computing](#man-distributed)
-   `multiplex`: if `true` then SSH multiplexing is used for SSH tunneling. Default is `false`.
-   `ssh`: the name or path of the SSH client executable used to start the workers. Default is `"ssh"`.
-   `sshflags`: specifies additional ssh options, e.g. `` sshflags=`-i /home/foo/bar.pem` ``
-   `max_parallel`: specifies the maximum number of workers connected to in parallel at a host. Defaults to 10.
-   `shell`: specifies the type of shell to which ssh connects on the workers.
    -   `shell=:posix`: a POSIX-compatible Unix/Linux shell (sh, ksh, bash, dash, zsh, etc.). The default.
    -   `shell=:csh`: a Unix C shell (csh, tcsh).
    -   `shell=:wincmd`: Microsoft Windows `cmd.exe`.
-   `dir`: specifies the working directory on the workers. Defaults to the host's current directory (as found by `pwd()`)
-   `enable_threaded_blas`: if `true` then BLAS will run on multiple threads in added processes. Default is `false`.
-   `exename`: name of the `julia` executable. Defaults to `"$(Sys.BINDIR)/julia"` or `"$(Sys.BINDIR)/julia-debug"` as the case may be. It is recommended that a common Julia version is used on all remote machines because serialization and code distribution might fail otherwise.
-   `exeflags`: additional flags passed to the worker processes.
-   `topology`: Specifies how the workers connect to each other. Sending a message between unconnected workers results in an error.
    -   `topology=:all_to_all`: All processes are connected to each other. The default.


# [Distributed Computing](#man-distributed)
    -   `topology=:master_worker`: Only the driver process, i.e. `pid` 1 connects to the workers. The workers do not connect to each other.
    -   `topology=:custom`: The `launch` method of the cluster manager specifies the connection topology via fields `ident` and `connect_idents` in `WorkerConfig`. A worker with a cluster manager identity `ident` will connect to all workers specified in `connect_idents`.
-   `lazy`: Applicable only with `topology=:all_to_all`. If `true`, worker-worker connections are setup lazily, i.e. they are setup at the first instance of a remote call between workers. Default is true.
-   `env`: provide an array of string pairs such as `env=["JULIA_DEPOT_PATH"=>"/depot"]` to request that environment variables are set on the remote machine. By default only the environment variable `JULIA_WORKER_TIMEOUT` is passed automatically from the local to the remote environment.
-   `cmdline_cookie`: pass the authentication cookie via the `--worker` commandline option. The (more secure) default behaviour of passing the cookie via ssh stdio may hang with Windows workers that use older (pre-ConPTY) Julia or Windows versions, in which case `cmdline_cookie=true` offers a work-around.
The keyword arguments `ssh`, `shell`, `env` and `cmdline_cookie` were added in Julia 1.6.
Environment variables:


# [Distributed Computing](#man-distributed)
If the master process fails to establish a connection with a newly launched worker within 60.0 seconds, the worker treats it as a fatal situation and terminates. This timeout can be controlled via environment variable `JULIA_WORKER_TIMEOUT`. The value of `JULIA_WORKER_TIMEOUT` on the master process specifies the number of seconds a newly launched worker waits for connection establishment.
```julia
addprocs(np::Integer=Sys.CPU_THREADS; restrict=true, kwargs...) -> List of process identifiers
```
Launch `np` workers on the local host using the in-built `LocalManager`.
Local workers inherit the current package environment (i.e., active project, [`LOAD_PATH`](../../base/constants/#Base.LOAD_PATH), and [`DEPOT_PATH`](../../base/constants/#Base.DEPOT_PATH)) from the main process.
Note that workers do not run a `~/.julia/config/startup.jl` startup script, nor do they synchronize their global state (such as command-line switches, global variables, new method definitions, and loaded modules) with any of the other running processes.
**Keyword arguments**:
-   `restrict::Bool`: if `true` (default) binding is restricted to `127.0.0.1`.
-   `dir`, `exename`, `exeflags`, `env`, `topology`, `lazy`, `enable_threaded_blas`: same effect as for `SSHManager`, see documentation for [`addprocs(machines::AbstractVector)`](#Distributed.addprocs).
The inheriting of the package environment and the `env` keyword argument were added in Julia 1.9.
```julia
nprocs()
```
Get the number of available processes.
**Examples**


# [Distributed Computing](#man-distributed)
```julia-repl
julia> nprocs()
3

julia> workers()
2-element Array{Int64,1}:
 2
 3
```
```julia
nworkers()
```
Get the number of available worker processes. This is one less than [`nprocs()`](#Distributed.nprocs). Equal to `nprocs()` if `nprocs() == 1`.
**Examples**
```julia-repl
$ julia -p 2

julia> nprocs()
3

julia> nworkers()
2
```
```julia
procs()
```
Return a list of all process identifiers, including pid 1 (which is not included by [`workers()`](#Distributed.workers)).
**Examples**
```julia-repl
$ julia -p 2

julia> procs()
3-element Array{Int64,1}:
 1
 2
 3
```
```julia
procs(pid::Integer)
```
Return a list of all process identifiers on the same physical node. Specifically all workers bound to the same ip-address as `pid` are returned.
```julia
workers()
```
Return a list of all worker process identifiers.
**Examples**
```julia-repl
$ julia -p 2

julia> workers()
2-element Array{Int64,1}:
 2
 3
```
```julia
rmprocs(pids...; waitfor=typemax(Int))
```
Remove the specified workers. Note that only process 1 can add or remove workers.
Argument `waitfor` specifies how long to wait for the workers to shut down:
-   If unspecified, `rmprocs` will wait until all requested `pids` are removed.
-   An [`ErrorException`](../../base/base/#Core.ErrorException) is raised if all workers cannot be terminated before the requested `waitfor` seconds.


# [Distributed Computing](#man-distributed)
-   With a `waitfor` value of 0, the call returns immediately with the workers scheduled for removal in a different task. The scheduled [`Task`](../../base/parallel/#Core.Task) object is returned. The user should call [`wait`](../../base/parallel/#Base.wait) on the task before invoking any other parallel calls.
**Examples**
```julia-repl
$ julia -p 5

julia> t = rmprocs(2, 3, waitfor=0)
Task (runnable) @0x0000000107c718d0

julia> wait(t)

julia> workers()
3-element Array{Int64,1}:
 4
 5
 6
```
```julia
interrupt(pids::Integer...)
```
Interrupt the current executing task on the specified workers. This is equivalent to pressing Ctrl-C on the local machine. If no arguments are given, all workers are interrupted.
```julia
interrupt(pids::AbstractVector=workers())
```
Interrupt the current executing task on the specified workers. This is equivalent to pressing Ctrl-C on the local machine. If no arguments are given, all workers are interrupted.
```julia
myid()
```
Get the id of the current process.
**Examples**
```julia-repl
julia> myid()
1

julia> remotecall_fetch(() -> myid(), 4)
4
```
```julia
pmap(f, [::AbstractWorkerPool], c...; distributed=true, batch_size=1, on_error=nothing, retry_delays=[], retry_check=nothing) -> collection
```
Transform collection `c` by applying `f` to each element using available workers and tasks.
For multiple collection arguments, apply `f` elementwise.


# [Distributed Computing](#man-distributed)
Note that `f` must be made available to all worker processes; see [Code Availability and Loading Packages](../../manual/distributed-computing/#code-availability) for details.
If a worker pool is not specified all available workers will be used via a [`CachingPool`](#Distributed.CachingPool).
By default, `pmap` distributes the computation over all specified workers. To use only the local process and distribute over tasks, specify `distributed=false`. This is equivalent to using [`asyncmap`](../../base/parallel/#Base.asyncmap). For example, `pmap(f, c; distributed=false)` is equivalent to `asyncmap(f,c; ntasks=()->nworkers())`
`pmap` can also use a mix of processes and tasks via the `batch_size` argument. For batch sizes greater than 1, the collection is processed in multiple batches, each of length `batch_size` or less. A batch is sent as a single request to a free worker, where a local [`asyncmap`](../../base/parallel/#Base.asyncmap) processes elements from the batch using multiple concurrent tasks.
Any error stops `pmap` from processing the remainder of the collection. To override this behavior you can specify an error handling function via argument `on_error` which takes in a single argument, i.e., the exception. The function can stop the processing by rethrowing the error, or, to continue, return any value which is then returned inline with the results to the caller.
Consider the following two examples. The first one returns the exception object inline, the second a 0 in place of any exception:


# [Distributed Computing](#man-distributed)
```julia-repl
julia> pmap(x->iseven(x) ? error("foo") : x, 1:4; on_error=identity)
4-element Array{Any,1}:
 1
  ErrorException("foo")
 3
  ErrorException("foo")

julia> pmap(x->iseven(x) ? error("foo") : x, 1:4; on_error=ex->0)
4-element Array{Int64,1}:
 1
 0
 3
 0
```
Errors can also be handled by retrying failed computations. Keyword arguments `retry_delays` and `retry_check` are passed through to [`retry`](../../base/base/#Base.retry) as keyword arguments `delays` and `check` respectively. If batching is specified, and an entire batch fails, all items in the batch are retried.
Note that if both `on_error` and `retry_delays` are specified, the `on_error` hook is called before retrying. If `on_error` does not throw (or rethrow) an exception, the element will not be retried.
Example: On errors, retry `f` on an element a maximum of 3 times without any delay between retries.
```julia
pmap(f, c; retry_delays = zeros(3))
```
Example: Retry `f` only if the exception is not of type [`InexactError`](../../base/base/#Core.InexactError), with exponentially increasing delays up to 3 times. Return a `NaN` in place for all `InexactError` occurrences.
```julia
pmap(f, c; on_error = e->(isa(e, InexactError) ? NaN : rethrow()), retry_delays = ExponentialBackOff(n = 3))
```
```julia
RemoteException(captured)
```


# [Distributed Computing](#man-distributed)
Exceptions on remote computations are captured and rethrown locally. A `RemoteException` wraps the `pid` of the worker and a captured exception. A `CapturedException` captures the remote exception and a serializable form of the call stack when the exception was raised.
```julia
ProcessExitedException(worker_id::Int)
```
After a client Julia process has exited, further attempts to reference the dead child will throw this exception.
```julia
Future(w::Int, rrid::RRID, v::Union{Some, Nothing}=nothing)
```
A `Future` is a placeholder for a single computation of unknown termination status and time. For multiple potential computations, see `RemoteChannel`. See `remoteref_id` for identifying an `AbstractRemoteRef`.
```julia
RemoteChannel(pid::Integer=myid())
```
Make a reference to a `Channel{Any}(1)` on process `pid`. The default `pid` is the current process.
```julia
RemoteChannel(f::Function, pid::Integer=myid())
```
Create references to remote channels of a specific size and type. `f` is a function that when executed on `pid` must return an implementation of an `AbstractChannel`.
For example, `RemoteChannel(()->Channel{Int}(10), pid)`, will return a reference to a channel of type `Int` and size 10 on `pid`.
The default `pid` is the current process.
```julia
fetch(x::Future)
```


# [Distributed Computing](#man-distributed)
Wait for and get the value of a [`Future`](../Future/#Future). The fetched value is cached locally. Further calls to `fetch` on the same reference return the cached value. If the remote value is an exception, throws a [`RemoteException`](#Distributed.RemoteException) which captures the remote exception and backtrace.
```julia
fetch(c::RemoteChannel)
```
Wait for and get a value from a [`RemoteChannel`](#Distributed.RemoteChannel). Exceptions raised are the same as for a [`Future`](../Future/#Future). Does not remove the item fetched.
```julia
fetch(x::Any)
```
Return `x`.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/task.jl#L375-L379)
```julia
remotecall(f, id::Integer, args...; kwargs...) -> Future
```
Call a function `f` asynchronously on the given arguments on the specified process. Return a [`Future`](../Future/#Future). Keyword arguments, if any, are passed through to `f`.
```julia
remotecall_wait(f, id::Integer, args...; kwargs...)
```
Perform a faster `wait(remotecall(...))` in one message on the `Worker` specified by worker id `id`. Keyword arguments, if any, are passed through to `f`.
See also [`wait`](../../base/parallel/#Base.wait) and [`remotecall`](#Distributed.remotecall-Tuple%7BAny,%20Integer,%20Vararg%7BAny%7D%7D).
```julia
remotecall_fetch(f, id::Integer, args...; kwargs...)
```


# [Distributed Computing](#man-distributed)
Perform `fetch(remotecall(...))` in one message. Keyword arguments, if any, are passed through to `f`. Any remote exceptions are captured in a [`RemoteException`](#Distributed.RemoteException) and thrown.
See also [`fetch`](../../base/parallel/#Base.fetch-Tuple%7BTask%7D) and [`remotecall`](#Distributed.remotecall-Tuple%7BAny,%20Integer,%20Vararg%7BAny%7D%7D).
**Examples**
```julia-repl
$ julia -p 2

julia> remotecall_fetch(sqrt, 2, 4)
2.0

julia> remotecall_fetch(sqrt, 2, -4)
ERROR: On worker 2:
DomainError with -4.0:
sqrt was called with a negative real argument but will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).
...
```
```julia
remote_do(f, id::Integer, args...; kwargs...) -> nothing
```
Executes `f` on worker `id` asynchronously. Unlike [`remotecall`](#Distributed.remotecall-Tuple%7BAny,%20Integer,%20Vararg%7BAny%7D%7D), it does not store the result of computation, nor is there a way to wait for its completion.
A successful invocation indicates that the request has been accepted for execution on the remote node.
While consecutive `remotecall`s to the same worker are serialized in the order they are invoked, the order of executions on the remote worker is undetermined. For example, `remote_do(f1, 2); remotecall(f2, 2); remote_do(f3, 2)` will serialize the call to `f1`, followed by `f2` and `f3` in that order. However, it is not guaranteed that `f1` is executed before `f3` on worker 2.


# [Distributed Computing](#man-distributed)
Any exceptions thrown by `f` are printed to [`stderr`](../../base/io-network/#Base.stderr) on the remote worker.
Keyword arguments, if any, are passed through to `f`.
```julia
put!(rr::RemoteChannel, args...)
```
Store a set of values to the [`RemoteChannel`](#Distributed.RemoteChannel). If the channel is full, blocks until space is available. Return the first argument.
```julia
put!(rr::Future, v)
```
Store a value to a [`Future`](../Future/#Future) `rr`. `Future`s are write-once remote references. A `put!` on an already set `Future` throws an `Exception`. All asynchronous remote calls return `Future`s and set the value to the return value of the call upon completion.
```julia
take!(rr::RemoteChannel, args...)
```
Fetch value(s) from a [`RemoteChannel`](#Distributed.RemoteChannel) `rr`, removing the value(s) in the process.
```julia
isready(rr::RemoteChannel, args...)
```
Determine whether a [`RemoteChannel`](#Distributed.RemoteChannel) has a value stored to it. Note that this function can cause race conditions, since by the time you receive its result it may no longer be true. However, it can be safely used on a [`Future`](../Future/#Future) since they are assigned only once.
```julia
isready(rr::Future)
```
Determine whether a [`Future`](../Future/#Future) has a value stored to it.
If the argument `Future` is owned by a different node, this call will block to wait for the answer. It is recommended to wait for `rr` in a separate task instead or to use a local [`Channel`](../../base/parallel/#Base.Channel) as a proxy:


# [Distributed Computing](#man-distributed)
```julia
p = 1
f = Future(p)
errormonitor(@async put!(f, remotecall_fetch(long_computation, p)))
isready(f)  # will not block
```
```julia
AbstractWorkerPool
```
Supertype for worker pools such as [`WorkerPool`](#Distributed.WorkerPool) and [`CachingPool`](#Distributed.CachingPool). An `AbstractWorkerPool` should implement:
-   [`push!`](../../base/collections/#Base.push!) - add a new worker to the overall pool (available + busy)
-   [`put!`](../../base/parallel/#Base.put!-Tuple%7BChannel,%20Any%7D) - put back a worker to the available pool
-   [`take!`](../../base/io-network/#Base.take!-Tuple%7BBase.GenericIOBuffer%7D) - take a worker from the available pool (to be used for remote function execution)
-   [`length`](../../base/collections/#Base.length) - number of workers available in the overall pool
-   [`isready`](../../base/parallel/#Base.isready-Tuple%7BChannel%7D) - return false if a `take!` on the pool would block, else true
The default implementations of the above (on a `AbstractWorkerPool`) require fields
-   `channel::Channel{Int}`
-   `workers::Set{Int}`
where `channel` contains free worker pids and `workers` is the set of all workers associated with this pool.
```julia
WorkerPool(workers::Union{Vector{Int},AbstractRange{Int}})
```
Create a `WorkerPool` from a vector or range of worker ids.
**Examples**


# [Distributed Computing](#man-distributed)
```julia-repl
$ julia -p 3

julia> WorkerPool([2, 3])
WorkerPool(Channel{Int64}(sz_max:9223372036854775807,sz_curr:2), Set([2, 3]), RemoteChannel{Channel{Any}}(1, 1, 6))

julia> WorkerPool(2:4)
WorkerPool(Channel{Int64}(sz_max:9223372036854775807,sz_curr:2), Set([4, 2, 3]), RemoteChannel{Channel{Any}}(1, 1, 7))
```
```julia
CachingPool(workers::Vector{Int})
```
An implementation of an `AbstractWorkerPool`. [`remote`](#Distributed.remote), [`remotecall_fetch`](#Distributed.remotecall_fetch-Tuple%7BAny,%20Integer,%20Vararg%7BAny%7D%7D), [`pmap`](#Distributed.pmap) (and other remote calls which execute functions remotely) benefit from caching the serialized/deserialized functions on the worker nodes, especially closures (which may capture large amounts of data).
The remote cache is maintained for the lifetime of the returned `CachingPool` object. To clear the cache earlier, use `clear!(pool)`.
For global variables, only the bindings are captured in a closure, not the data. `let` blocks can be used to capture global data.
**Examples**
```julia
const foo = rand(10^8);
wp = CachingPool(workers())
let foo = foo
    pmap(i -> sum(foo) + i, wp, 1:100);
end
```
The above would transfer `foo` only once to each worker.
```julia
default_worker_pool()
```


# [Distributed Computing](#man-distributed)
[`AbstractWorkerPool`](#Distributed.AbstractWorkerPool) containing idle [`workers`](#Distributed.workers) - used by `remote(f)` and [`pmap`](#Distributed.pmap) (by default). Unless one is explicitly set via `default_worker_pool!(pool)`, the default worker pool is initialized to a [`WorkerPool`](#Distributed.WorkerPool).
**Examples**
```julia-repl
$ julia -p 3

julia> default_worker_pool()
WorkerPool(Channel{Int64}(sz_max:9223372036854775807,sz_curr:3), Set([4, 2, 3]), RemoteChannel{Channel{Any}}(1, 1, 4))
```
```julia
clear!(syms, pids=workers(); mod=Main)
```
Clears global bindings in modules by initializing them to `nothing`. `syms` should be of type [`Symbol`](../../base/base/#Core.Symbol) or a collection of `Symbol`s . `pids` and `mod` identify the processes and the module in which global variables are to be reinitialized. Only those names found to be defined under `mod` are cleared.
An exception is raised if a global constant is requested to be cleared.
```julia
clear!(pool::CachingPool) -> pool
```
Removes all cached functions from all participating workers.
```julia
remote([p::AbstractWorkerPool], f) -> Function
```
Return an anonymous function that executes function `f` on an available worker (drawn from [`WorkerPool`](#Distributed.WorkerPool) `p` if provided) using [`remotecall_fetch`](#Distributed.remotecall_fetch-Tuple%7BAny,%20Integer,%20Vararg%7BAny%7D%7D).
```julia
remotecall(f, pool::AbstractWorkerPool, args...; kwargs...) -> Future
```


# [Distributed Computing](#man-distributed)
[`WorkerPool`](#Distributed.WorkerPool) variant of `remotecall(f, pid, ....)`. Wait for and take a free worker from `pool` and perform a `remotecall` on it.
**Examples**
```julia-repl
$ julia -p 3

julia> wp = WorkerPool([2, 3]);

julia> A = rand(3000);

julia> f = remotecall(maximum, wp, A)
Future(2, 1, 6, nothing)
```
In this example, the task ran on pid 2, called from pid 1.
```julia
remotecall_wait(f, pool::AbstractWorkerPool, args...; kwargs...) -> Future
```
[`WorkerPool`](#Distributed.WorkerPool) variant of `remotecall_wait(f, pid, ....)`. Wait for and take a free worker from `pool` and perform a `remotecall_wait` on it.
**Examples**
```julia-repl
$ julia -p 3

julia> wp = WorkerPool([2, 3]);

julia> A = rand(3000);

julia> f = remotecall_wait(maximum, wp, A)
Future(3, 1, 9, nothing)

julia> fetch(f)
0.9995177101692958
```
```julia
remotecall_fetch(f, pool::AbstractWorkerPool, args...; kwargs...) -> result
```
[`WorkerPool`](#Distributed.WorkerPool) variant of `remotecall_fetch(f, pid, ....)`. Waits for and takes a free worker from `pool` and performs a `remotecall_fetch` on it.
**Examples**
```julia-repl
$ julia -p 3

julia> wp = WorkerPool([2, 3]);

julia> A = rand(3000);

julia> remotecall_fetch(maximum, wp, A)
0.9995177101692958
```
```julia
remote_do(f, pool::AbstractWorkerPool, args...; kwargs...) -> nothing
```
[`WorkerPool`](#Distributed.WorkerPool) variant of `remote_do(f, pid, ....)`. Wait for and take a free worker from `pool` and perform a `remote_do` on it.
```julia
@spawn expr
```


# [Distributed Computing](#man-distributed)
Create a closure around an expression and run it on an automatically-chosen process, returning a [`Future`](../Future/#Future) to the result. This macro is deprecated; `@spawnat :any expr` should be used instead.
**Examples**
```julia-repl
julia> addprocs(3);

julia> f = @spawn myid()
Future(2, 1, 5, nothing)

julia> fetch(f)
2

julia> f = @spawn myid()
Future(3, 1, 7, nothing)

julia> fetch(f)
3
```
As of Julia 1.3 this macro is deprecated. Use `@spawnat :any` instead.
```julia
@spawnat p expr
```
Create a closure around an expression and run the closure asynchronously on process `p`. Return a [`Future`](../Future/#Future) to the result. If `p` is the quoted literal symbol `:any`, then the system will pick a processor to use automatically.
**Examples**
```julia-repl
julia> addprocs(3);

julia> f = @spawnat 2 myid()
Future(2, 1, 3, nothing)

julia> fetch(f)
2

julia> f = @spawnat :any myid()
Future(3, 1, 7, nothing)

julia> fetch(f)
3
```
The `:any` argument is available as of Julia 1.3.
```julia
@fetch expr
```
Equivalent to `fetch(@spawnat :any expr)`. See [`fetch`](../../base/parallel/#Base.fetch-Tuple%7BTask%7D) and [`@spawnat`](#Distributed.@spawnat).
**Examples**
```julia-repl
julia> addprocs(3);

julia> @fetch myid()
2

julia> @fetch myid()
3

julia> @fetch myid()
4

julia> @fetch myid()
2
```
```julia
@fetchfrom
```
Equivalent to `fetch(@spawnat p expr)`. See [`fetch`](../../base/parallel/#Base.fetch-Tuple%7BTask%7D) and [`@spawnat`](#Distributed.@spawnat).
**Examples**


# [Distributed Computing](#man-distributed)
```julia-repl
julia> addprocs(3);

julia> @fetchfrom 2 myid()
2

julia> @fetchfrom 4 myid()
4
```
```julia
@distributed
```
A distributed memory, parallel for loop of the form :
```julia
@distributed [reducer] for var = range
    body
end
```
The specified range is partitioned and locally executed across all workers. In case an optional reducer function is specified, `@distributed` performs local reductions on each worker with a final reduction on the calling process.
Note that without a reducer function, `@distributed` executes asynchronously, i.e. it spawns independent tasks on all available workers and returns immediately without waiting for completion. To wait for completion, prefix the call with [`@sync`](../../base/parallel/#Base.@sync), like :
```julia
@sync @distributed for var = range
    body
end
```
```julia
@everywhere [procs()] expr
```
Execute an expression under `Main` on all `procs`. Errors on any of the processes are collected into a [`CompositeException`](../../base/base/#Base.CompositeException) and thrown. For example:
```julia
@everywhere bar = 1
```
will define `Main.bar` on all current processes. Any processes added later (say with [`addprocs()`](#Distributed.addprocs)) will not have the expression defined.
Unlike [`@spawnat`](#Distributed.@spawnat), `@everywhere` does not capture any local variables. Instead, local variables can be broadcast using interpolation:
```julia
foo = 1
@everywhere bar = $foo
```


# [Distributed Computing](#man-distributed)
The optional argument `procs` allows specifying a subset of all processes to have execute the expression.
Similar to calling `remotecall_eval(Main, procs, expr)`, but with two extra features:
```julia
- `using` and `import` statements run on the calling process first, to ensure
  packages are precompiled.
- The current source file path used by `include` is propagated to other processes.
```
```julia
remoteref_id(r::AbstractRemoteRef) -> RRID
```
`Future`s and `RemoteChannel`s are identified by fields:
-   `where` - refers to the node where the underlying object/storage referred to by the reference actually exists.
-   `whence` - refers to the node the remote reference was created from. Note that this is different from the node where the underlying object referred to actually exists. For example calling `RemoteChannel(2)` from the master process would result in a `where` value of 2 and a `whence` value of 1.
-   `id` is unique across all references created from the worker specified by `whence`.
Taken together, `whence` and `id` uniquely identify a reference across all workers.
`remoteref_id` is a low-level API which returns a `RRID` object that wraps `whence` and `id` values of a remote reference.
```julia
channel_from_id(id) -> c
```
A low-level API which returns the backing `AbstractChannel` for an `id` returned by [`remoteref_id`](#Distributed.remoteref_id). The call is valid only on the node where the backing channel exists.
```julia
worker_id_from_socket(s) -> pid
```


# [Distributed Computing](#man-distributed)
A low-level API which, given a `IO` connection or a `Worker`, returns the `pid` of the worker it is connected to. This is useful when writing custom [`serialize`](../Serialization/#Serialization.serialize) methods for a type, which optimizes the data written out depending on the receiving process id.
```julia
cluster_cookie() -> cookie
```
Return the cluster cookie.
```julia
cluster_cookie(cookie) -> cookie
```
Set the passed cookie as the cluster cookie, then returns it.


## [Cluster Manager Interface](#Cluster-Manager-Interface)
This interface provides a mechanism to launch and manage Julia workers on different cluster environments. There are two types of managers present in Base: `LocalManager`, for launching additional workers on the same host, and `SSHManager`, for launching on remote hosts via `ssh`. TCP/IP sockets are used to connect and transport messages between processes. It is possible for Cluster Managers to provide a different transport.
```julia
ClusterManager
```
Supertype for cluster managers, which control workers processes as a cluster. Cluster managers implement how workers can be added, removed and communicated with. `SSHManager` and `LocalManager` are subtypes of this.
```julia
WorkerConfig
```
Type used by [`ClusterManager`](#Distributed.ClusterManager)s to control workers added to their clusters. Some fields are used by all cluster managers to access a host:
-   `io` – the connection used to access the worker (a subtype of `IO` or `Nothing`)
-   `host` – the host address (either a `String` or `Nothing`)
-   `port` – the port on the host used to connect to the worker (either an `Int` or `Nothing`)
Some are used by the cluster manager to add workers to an already-initialized host:
-   `count` – the number of workers to be launched on the host
-   `exename` – the path to the Julia executable on the host, defaults to `"$(Sys.BINDIR)/julia"` or `"$(Sys.BINDIR)/julia-debug"`
-   `exeflags` – flags to use when launching Julia remotely
The `userdata` field is used to store information for each worker by external managers.


## [Cluster Manager Interface](#Cluster-Manager-Interface)
Some fields are used by `SSHManager` and similar managers:
-   `tunnel` – `true` (use tunneling), `false` (do not use tunneling), or [`nothing`](../../base/constants/#Core.nothing) (use default for the manager)
-   `multiplex` – `true` (use SSH multiplexing for tunneling) or `false`
-   `forward` – the forwarding option used for `-L` option of ssh
-   `bind_addr` – the address on the remote host to bind to
-   `sshflags` – flags to use in establishing the SSH connection
-   `max_parallel` – the maximum number of workers to connect to in parallel on the host
Some fields are used by both `LocalManager`s and `SSHManager`s:
-   `connect_at` – determines whether this is a worker-to-worker or driver-to-worker setup call
-   `process` – the process which will be connected (usually the manager will assign this during [`addprocs`](#Distributed.addprocs))
-   `ospid` – the process ID according to the host OS, used to interrupt worker processes
-   `environ` – private dictionary used to store temporary information by Local/SSH managers
-   `ident` – worker as identified by the [`ClusterManager`](#Distributed.ClusterManager)
-   `connect_idents` – list of worker ids the worker must connect to if using a custom topology
-   `enable_threaded_blas` – `true`, `false`, or `nothing`, whether to use threaded BLAS or not on the workers
```julia
launch(manager::ClusterManager, params::Dict, launched::Array, launch_ntfy::Condition)
```


## [Cluster Manager Interface](#Cluster-Manager-Interface)
Implemented by cluster managers. For every Julia worker launched by this function, it should append a `WorkerConfig` entry to `launched` and notify `launch_ntfy`. The function MUST exit once all workers, requested by `manager` have been launched. `params` is a dictionary of all keyword arguments [`addprocs`](#Distributed.addprocs) was called with.
```julia
manage(manager::ClusterManager, id::Integer, config::WorkerConfig. op::Symbol)
```
Implemented by cluster managers. It is called on the master process, during a worker's lifetime, with appropriate `op` values:
-   with `:register`/`:deregister` when a worker is added / removed from the Julia worker pool.
-   with `:interrupt` when `interrupt(workers)` is called. The `ClusterManager` should signal the appropriate worker with an interrupt signal.
-   with `:finalize` for cleanup purposes.
```julia
kill(manager::ClusterManager, pid::Int, config::WorkerConfig)
```
Implemented by cluster managers. It is called on the master process, by [`rmprocs`](#Distributed.rmprocs). It should cause the remote worker specified by `pid` to exit. `kill(manager::ClusterManager.....)` executes a remote `exit()` on `pid`.
```julia
connect(manager::ClusterManager, pid::Int, config::WorkerConfig) -> (instrm::IO, outstrm::IO)
```


## [Cluster Manager Interface](#Cluster-Manager-Interface)
Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id `pid`, specified by `config` and return a pair of `IO` objects. Messages from `pid` to current process will be read off `instrm`, while messages to be sent to `pid` will be written to `outstrm`. The custom transport implementation must ensure that messages are delivered and received completely and in order. `connect(manager::ClusterManager.....)` sets up TCP/IP socket connections in-between workers.
```julia
init_worker(cookie::AbstractString, manager::ClusterManager=DefaultClusterManager())
```
Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. Command line argument `--worker[=<cookie>]` has the effect of initializing a process as a worker using TCP/IP sockets for transport. `cookie` is a [`cluster_cookie`](#Distributed.cluster_cookie-Tuple%7B%7D).
```julia
start_worker([out::IO=stdout], cookie::AbstractString=readline(stdin); close_stdin::Bool=true, stderr_to_stdout::Bool=true)
```
`start_worker` is an internal function which is the default entry point for worker processes connecting via TCP/IP. It sets up the process as a Julia cluster worker.
host:port information is written to stream `out` (defaults to stdout).


## [Cluster Manager Interface](#Cluster-Manager-Interface)
The function reads the cookie from stdin if required, and listens on a free port (or if specified, the port in the `--bind-to` command line option) and schedules tasks to process incoming TCP connections and requests. It also (optionally) closes stdin and redirects stderr to stdout.
It does not return.
```julia
process_messages(r_stream::IO, w_stream::IO, incoming::Bool=true)
```
Called by cluster managers using custom transports. It should be called when the custom transport implementation receives the first message from a remote worker. The custom transport must manage a logical connection to the remote worker and provide two `IO` objects, one for incoming messages and the other for messages addressed to the remote worker. If `incoming` is `true`, the remote peer initiated the connection. Whichever of the pair initiates the connection sends the cluster cookie and its Julia version number to perform the authentication handshake.
See also [`cluster_cookie`](#Distributed.cluster_cookie-Tuple%7B%7D).
```julia
default_addprocs_params(mgr::ClusterManager) -> Dict{Symbol, Any}
```
Implemented by cluster managers. The default keyword parameters passed when calling `addprocs(mgr)`. The minimal set of options is available by calling `default_addprocs_params()`
------------------------------------------------------------------------


# Downloads · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/Downloads/


# [Downloads](#Downloads)
```julia
download(url, [ output = tempname() ];
    [ method = "GET", ]
    [ headers = <none>, ]
    [ timeout = <none>, ]
    [ progress = <none>, ]
    [ verbose = false, ]
    [ debug = <none>, ]
    [ downloader = <default>, ]
) -> output

    url        :: AbstractString
    output     :: Union{AbstractString, AbstractCmd, IO}
    method     :: AbstractString
    headers    :: Union{AbstractVector, AbstractDict}
    timeout    :: Real
    progress   :: (total::Integer, now::Integer) --> Any
    verbose    :: Bool
    debug      :: (type, message) --> Any
    downloader :: Downloader
```
Download a file from the given url, saving it to `output` or if not specified, a temporary path. The `output` can also be an `IO` handle, in which case the body of the response is streamed to that handle and the handle is returned. If `output` is a command, the command is run and output is sent to it on stdin.
If the `downloader` keyword argument is provided, it must be a `Downloader` object. Resources and connections will be shared between downloads performed by the same `Downloader` and cleaned up automatically when the object is garbage collected or there have been no downloads performed with it for a grace period. See `Downloader` for more info about configuration and usage.
If the `headers` keyword argument is provided, it must be a vector or dictionary whose elements are all pairs of strings. These pairs are passed as headers when downloading URLs with protocols that supports them, such as HTTP/S.


# [Downloads](#Downloads)
The `timeout` keyword argument specifies a timeout for the download to complete in seconds, with a resolution of milliseconds. By default no timeout is set, but this can also be explicitly requested by passing a timeout value of `Inf`. Separately, if 20 seconds elapse without receiving any data, the download will timeout. See extended help for how to disable this timeout.
If the `progress` keyword argument is provided, it must be a callback function which will be called whenever there are updates about the size and status of the ongoing download. The callback must take two integer arguments: `total` and `now` which are the total size of the download in bytes, and the number of bytes which have been downloaded so far. Note that `total` starts out as zero and remains zero until the server gives an indication of the total size of the download (e.g. with a `Content-Length` header), which may never happen. So a well-behaved progress callback should handle a total size of zero gracefully.


# [Downloads](#Downloads)
If the `verbose` option is set to true, `libcurl`, which is used to implement the download functionality will print debugging information to `stderr`. If the `debug` option is set to a function accepting two `String` arguments, then the verbose option is ignored and instead the data that would have been printed to `stderr` is passed to the `debug` callback with `type` and `message` arguments. The `type` argument indicates what kind of event has occurred, and is one of: `TEXT`, `HEADER IN`, `HEADER OUT`, `DATA IN`, `DATA OUT`, `SSL DATA IN` or `SSL DATA OUT`. The `message` argument is the description of the debug event.
**Extended Help**
For further customization, use a [`Downloader`](#Downloads.Downloader) and [`easy_hook`s](https://github.com/JuliaLang/Downloads.jl#mutual-tls-using-downloads). For example, to disable the 20 second timeout when no data is received, you may use the following:
```jl
downloader = Downloads.Downloader()
downloader.easy_hook = (easy, info) -> Downloads.Curl.setopt(easy, Downloads.Curl.CURLOPT_LOW_SPEED_TIME, 0)

Downloads.download("https://httpbingo.julialang.org/delay/30"; downloader)
```


# [Downloads](#Downloads)
```julia
request(url;
    [ input = <none>, ]
    [ output = <none>, ]
    [ method = input ? "PUT" : output ? "GET" : "HEAD", ]
    [ headers = <none>, ]
    [ timeout = <none>, ]
    [ progress = <none>, ]
    [ verbose = false, ]
    [ debug = <none>, ]
    [ throw = true, ]
    [ downloader = <default>, ]
    [ interrupt = <none>, ]
) -> Union{Response, RequestError}

    url        :: AbstractString
    input      :: Union{AbstractString, AbstractCmd, IO}
    output     :: Union{AbstractString, AbstractCmd, IO}
    method     :: AbstractString
    headers    :: Union{AbstractVector, AbstractDict}
    timeout    :: Real
    progress   :: (dl_total, dl_now, ul_total, ul_now) --> Any
    verbose    :: Bool
    debug      :: (type, message) --> Any
    throw      :: Bool
    downloader :: Downloader
    interrupt  :: Base.Event
```
Make a request to the given url, returning a `Response` object capturing the status, headers and other information about the response. The body of the response is written to `output` if specified and discarded otherwise. For HTTP/S requests, if an `input` stream is given, a `PUT` request is made; otherwise if an `output` stream is given, a `GET` request is made; if neither is given a `HEAD` request is made. For other protocols, appropriate default methods are used based on what combination of input and output are requested. The following options differ from the `download` function:
-   `input` allows providing a request body; if provided default to `PUT` request


# [Downloads](#Downloads)
-   `progress` is a callback taking four integers for upload and download progress
-   `throw` controls whether to throw or return a `RequestError` on request error
Note that unlike `download` which throws an error if the requested URL could not be downloaded (indicated by non-2xx status code), `request` returns a `Response` object no matter what the status code of the response is. If there is an error with getting a response at all, then a `RequestError` is thrown or returned.
If the `interrupt` keyword argument is provided, it must be a `Base.Event` object. If the event is triggered while the request is in progress, the request will be cancelled and an error will be thrown. This can be used to interrupt a long running request, for example if the user wants to cancel a download.
```julia
struct Response
    proto   :: String
    url     :: String
    status  :: Int
    message :: String
    headers :: Vector{Pair{String,String}}
end
```
`Response` is a type capturing the properties of a successful response to a request as an object. It has the following fields:
-   `proto`: the protocol that was used to get the response
-   `url`: the URL that was ultimately requested after following redirects
-   `status`: the status code of the response, indicating success, failure, etc.
-   `message`: a textual message describing the nature of the response
-   `headers`: any headers that were returned with the response


# [Downloads](#Downloads)
The meaning and availability of some of these responses depends on the protocol used for the request. For many protocols, including HTTP/S and S/FTP, a 2xx status code indicates a successful response. For responses in protocols that do not support headers, the headers vector will be empty. HTTP/2 does not include a status message, only a status code, so the message will be empty.
```julia
struct RequestError <: ErrorException
    url      :: String
    code     :: Int
    message  :: String
    response :: Response
end
```
`RequestError` is a type capturing the properties of a failed response to a request as an exception object:
-   `url`: the original URL that was requested without any redirects
-   `code`: the libcurl error code; `0` if a protocol-only error occurred
-   `message`: the libcurl error message indicating what went wrong
-   `response`: response object capturing what response info is available
The same `RequestError` type is thrown by `download` if the request was successful but there was a protocol-level error indicated by a status code that is not in the 2xx range, in which case `code` will be zero and the `message` field will be the empty string. The `request` API only throws a `RequestError` if the libcurl error `code` is non-zero, in which case the included `response` object is likely to have a `status` of zero and an empty message. There are, however, situations where a curl-level error is thrown due to a protocol error, in which case both the inner and outer code and message may be of interest.


# [Downloads](#Downloads)
```julia
Downloader(; [ grace::Real = 30 ])
```
`Downloader` objects are used to perform individual `download` operations. Connections, name lookups and other resources are shared within a `Downloader`. These connections and resources are cleaned up after a configurable grace period (default: 30 seconds) since anything was downloaded with it, or when it is garbage collected, whichever comes first. If the grace period is set to zero, all resources will be cleaned up immediately as soon as there are no more ongoing downloads in progress. If the grace period is set to `Inf` then resources are not cleaned up until `Downloader` is garbage collected.
------------------------------------------------------------------------


# File Events · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/FileWatching/


# [File Events](#lib-filewatching)
```julia
poll_fd(fd, timeout_s::Real=-1; readable=false, writable=false)
```
Monitor a file descriptor `fd` for changes in the read or write availability, and with a timeout given by `timeout_s` seconds.
The keyword arguments determine which of read and/or write status should be monitored; at least one of them must be set to `true`.
The returned value is an object with boolean fields `readable`, `writable`, and `timedout`, giving the result of the polling.
```julia
poll_file(path::AbstractString, interval_s::Real=5.007, timeout_s::Real=-1) -> (previous::StatStruct, current)
```
Monitor a file for changes by polling every `interval_s` seconds until a change occurs or `timeout_s` seconds have elapsed. The `interval_s` should be a long period; the default is 5.007 seconds.
Returns a pair of status objects `(previous, current)` when a change is detected. The `previous` status is always a `StatStruct`, but it may have all of the fields zeroed (indicating the file didn't previously exist, or wasn't previously accessible).
The `current` status object may be a `StatStruct`, an `EOFError` (indicating the timeout elapsed), or some other `Exception` subtype (if the `stat` operation failed - for example, if the path does not exist).
To determine when a file was modified, compare `current isa StatStruct && mtime(prev) != mtime(current)` to detect notification of changes. However, using [`watch_file`](#FileWatching.watch_file) for this operation is preferred, since it is more reliable and efficient, although in some situations it may not be available.


# [File Events](#lib-filewatching)
```julia
watch_file(path::AbstractString, timeout_s::Real=-1)
```
Watch file or directory `path` for changes until a change occurs or `timeout_s` seconds have elapsed. This function does not poll the file system and instead uses platform-specific functionality to receive notifications from the operating system (e.g. via inotify on Linux). See the NodeJS documentation linked below for details.
The returned value is an object with boolean fields `renamed`, `changed`, and `timedout`, giving the result of watching the file.
This behavior of this function varies slightly across platforms. See <https://nodejs.org/api/fs.html#fs_caveats> for more detailed information.
```julia
watch_folder(path::AbstractString, timeout_s::Real=-1)
```
Watches a file or directory `path` for changes until a change has occurred or `timeout_s` seconds have elapsed. This function does not poll the file system and instead uses platform-specific functionality to receive notifications from the operating system (e.g. via inotify on Linux). See the NodeJS documentation linked below for details.
This will continuing tracking changes for `path` in the background until `unwatch_folder` is called on the same `path`.
The returned value is an pair where the first field is the name of the changed file (if available) and the second field is an object with boolean fields `renamed`, `changed`, and `timedout`, giving the event.
This behavior of this function varies slightly across platforms. See <https://nodejs.org/api/fs.html#fs_caveats> for more detailed information.


# [File Events](#lib-filewatching)
```julia
unwatch_folder(path::AbstractString)
```
Stop background tracking of changes for `path`. It is not recommended to do this while another task is waiting for `watch_folder` to return on the same path, as the result may be unpredictable.


# [Pidfile](#Pidfile)
A simple utility tool for creating advisory pidfiles (lock files).


## [Primary Functions](#Primary-Functions)
```julia
mkpidlock([f::Function], at::String, [pid::Cint]; kwopts...)
mkpidlock(at::String, proc::Process; kwopts...)
```
Create a pidfile lock for the path "at" for the current process or the process identified by pid or proc. Can take a function to execute once locked, for usage in `do` blocks, after which the lock will be automatically closed. If the lock fails and `wait` is false, then an error is thrown.
The lock will be released by either `close`, a `finalizer`, or shortly after `proc` exits. Make sure the return value is live through the end of the critical section of your program, so the `finalizer` does not reclaim it early.
Optional keyword arguments:
-   `mode`: file access mode (modified by the process umask). Defaults to world-readable.
-   `poll_interval`: Specify the maximum time to between attempts (if `watch_file` doesn't work)
-   `stale_age`: Delete an existing pidfile (ignoring the lock) if it is older than this many seconds, based on its mtime. The file won't be deleted until 5x longer than this if the pid in the file appears that it may be valid. Or 25x longer if `refresh` is overridden to 0 to disable lock refreshing. By default this is disabled (`stale_age` = 0), but a typical recommended value would be about 3-5x an estimated normal completion time.
-   `refresh`: Keeps a lock from becoming stale by updating the mtime every interval of time that passes. By default, this is set to `stale_age/2`, which is the recommended value.


## [Primary Functions](#Primary-Functions)
-   `wait`: If true, block until we get the lock, if false, raise error if lock fails.
```julia
trymkpidlock([f::Function], at::String, [pid::Cint]; kwopts...)
trymkpidlock(at::String, proc::Process; kwopts...)
```
Like `mkpidlock` except returns `false` instead of waiting if the file is already locked.
This function requires at least Julia 1.10.
```julia
close(lock::LockMonitor)
```
Release a pidfile lock.


## [Helper Functions](#Helper-Functions)
```julia
open_exclusive(path::String; mode, poll_interval, wait, stale_age, refresh) :: File
```
Create a new a file for read-write advisory-exclusive access. If `wait` is `false` then error out if the lock files exist otherwise block until we get the lock.
For a description of the keyword arguments, see [`mkpidlock`](#FileWatching.Pidfile.mkpidlock).
```julia
tryopen_exclusive(path::String, mode::Integer = 0o444) :: Union{Void, File}
```
Try to create a new file for read-write advisory-exclusive access, return nothing if it already exists.
```julia
write_pidfile(io, pid)
```
Write our pidfile format to an open IO descriptor.
```julia
parse_pidfile(file::Union{IO, String}) => (pid, hostname, age)
```
Attempt to parse our pidfile format, replaced an element with (0, "", 0.0), respectively, for any read that failed.
```julia
stale_pidfile(path::String, stale_age::Real, refresh::Real) :: Bool
```
Helper function for `open_exclusive` for deciding if a pidfile is stale.
```julia
isvalidpid(hostname::String, pid::Cuint) :: Bool
```
Attempt to conservatively estimate whether pid is a valid process id.
```julia
Base.touch(::Pidfile.LockMonitor)
```
Update the `mtime` on the lock, to indicate it is still fresh.
See also the `refresh` keyword in the [`mkpidlock`](#FileWatching.Pidfile.mkpidlock) constructor.
------------------------------------------------------------------------


# Future · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/Future/


# [Future](#Future)
The `Future` module implements future behavior of already existing functions, which will replace the current version in a future release of Julia.
```julia
Future.copy!(dst, src) -> dst
```
Copy `src` into `dst`.
This function has moved to `Base` with Julia 1.1, consider using `copy!(dst, src)` instead. `Future.copy!` will be deprecated in the future.
```julia
randjump(r::MersenneTwister, steps::Integer) -> MersenneTwister
```
Create an initialized `MersenneTwister` object, whose state is moved forward (without generating numbers) from `r` by `steps` steps. One such step corresponds to the generation of two `Float64` numbers. For each different value of `steps`, a large polynomial has to be generated internally. One is already pre-computed for `steps=big(10)^20`.
------------------------------------------------------------------------


# Interactive Utilities · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/InteractiveUtils/


# [Interactive Utilities](#man-interactive-utils)
The `InteractiveUtils` module provides utilities for interactive use of Julia, such as code introspection and clipboard access. It is intended for interactive work and is loaded automatically in [interactive mode](../../manual/command-line-interface/#command-line-interface).
```julia
apropos([io::IO=stdout], pattern::Union{AbstractString,Regex})
```
Search available docstrings for entries containing `pattern`.
When `pattern` is a string, case is ignored. Results are printed to `io`.
`apropos` can be called from the help mode in the REPL by wrapping the query in double quotes:
```julia
help?> "pattern"
```
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/docs/Docs.jl#L687-L698)
```julia
varinfo(m::Module=Main, pattern::Regex=r""; all=false, imported=false, recursive=false, sortby::Symbol=:name, minsize::Int=0)
```
Return a markdown table giving information about public global variables in a module, optionally restricted to those matching `pattern`.
The memory consumption estimate is an approximate lower bound on the size of the internal structure of the object.
-   `all` : also list non-public objects defined in the module, deprecated objects, and compiler-generated objects.
-   `imported` : also list objects explicitly imported from other modules.
-   `recursive` : recursively include objects in sub-modules, observing the same settings in each.
-   `sortby` : the column to sort results by. Options are `:name` (default), `:size`, and `:summary`.


# [Interactive Utilities](#man-interactive-utils)
-   `minsize` : only includes objects with size at least `minsize` bytes. Defaults to `0`.
The output of `varinfo` is intended for display purposes only. See also [`names`](../../base/base/#Base.names) to get an array of symbols defined in a module, which is suitable for more general manipulations.
```julia
versioninfo(io::IO=stdout; verbose::Bool=false)
```
Print information about the version of Julia in use. The output is controlled with boolean keyword arguments:
-   `verbose`: print all additional information
The output of this function may contain sensitive information. Before sharing the output, please review the output and remove any data that should not be shared publicly.
See also: [`VERSION`](../../base/constants/#Base.VERSION).
```julia
methodswith(typ[, module or function]; supertypes::Bool=false])
```
Return an array of methods with an argument of type `typ`.
The optional second argument restricts the search to a particular module or function (the default is all top-level modules).
If keyword `supertypes` is `true`, also return arguments with a parent type of `typ`, excluding type `Any`.
See also: [`methods`](../../base/base/#Base.methods).
```julia
subtypes(T::DataType)
```
Return a list of immediate subtypes of DataType `T`. Note that all currently loaded subtypes are included, including those not visible in the current module.
See also [`supertype`](../../base/base/#Base.supertype), [`supertypes`](#InteractiveUtils.supertypes), [`methodswith`](#InteractiveUtils.methodswith).
**Examples**


# [Interactive Utilities](#man-interactive-utils)
```julia-repl
julia> subtypes(Integer)
3-element Vector{Any}:
 Bool
 Signed
 Unsigned
```
```julia
supertypes(T::Type)
```
Return a tuple `(T, ..., Any)` of `T` and all its supertypes, as determined by successive calls to the [`supertype`](../../base/base/#Base.supertype) function, listed in order of `<:` and terminated by `Any`.
See also [`subtypes`](#InteractiveUtils.subtypes).
**Examples**
```julia-repl
julia> supertypes(Int)
(Int64, Signed, Integer, Real, Number, Any)
```
```julia
edit(path::AbstractString, line::Integer=0, column::Integer=0)
```
Edit a file or directory optionally providing a line number to edit the file at. Return to the `julia` prompt when you quit the editor. The editor can be changed by setting `JULIA_EDITOR`, `VISUAL` or `EDITOR` as an environment variable.
The `column` argument requires at least Julia 1.9.
See also [`InteractiveUtils.define_editor`](#InteractiveUtils.define_editor).
```julia
edit(function, [types])
edit(module)
```
Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. For modules, open the main source file. The module needs to be loaded with `using` or `import` first.
`edit` on modules requires at least Julia 1.1.
To ensure that the file can be opened at the given line, you may need to call `InteractiveUtils.define_editor` first.
```julia
@edit
```


# [Interactive Utilities](#man-interactive-utils)
Evaluates the arguments to the function or macro call, determines their types, and calls the [`edit`](#InteractiveUtils.edit-Tuple%7BAbstractString,%20Integer%7D) function on the resulting expression.
See also: [`@less`](#InteractiveUtils.@less), [`@which`](#InteractiveUtils.@which).
```julia
define_editor(fn, pattern; wait=false)
```
Define a new editor matching `pattern` that can be used to open a file (possibly at a given line number) using `fn`.
The `fn` argument is a function that determines how to open a file with the given editor. It should take four arguments, as follows:
-   `cmd` - a base command object for the editor
-   `path` - the path to the source file to open
-   `line` - the line number to open the editor at
-   `column` - the column number to open the editor at
Editors which cannot open to a specific line with a command or a specific column may ignore the `line` and/or `column` argument. The `fn` callback must return either an appropriate `Cmd` object to open a file or `nothing` to indicate that they cannot edit this file. Use `nothing` to indicate that this editor is not appropriate for the current environment and another editor should be attempted. It is possible to add more general editing hooks that need not spawn external commands by pushing a callback directly to the vector `EDITOR_CALLBACKS`.


# [Interactive Utilities](#man-interactive-utils)
The `pattern` argument is a string, regular expression, or an array of strings and regular expressions. For the `fn` to be called, one of the patterns must match the value of `EDITOR`, `VISUAL` or `JULIA_EDITOR`. For strings, the string must equal the [`basename`](../../base/file/#Base.Filesystem.basename) of the first word of the editor command, with its extension, if any, removed. E.g. "vi" doesn't match "vim -g" but matches "/usr/bin/vi -m"; it also matches `vi.exe`. If `pattern` is a regex it is matched against all of the editor command as a shell-escaped string. An array pattern matches if any of its items match. If multiple editors match, the one added most recently is used.
By default julia does not wait for the editor to close, running it in the background. However, if the editor is terminal based, you will probably want to set `wait=true` and julia will wait for the editor to close before resuming.
If one of the editor environment variables is set, but no editor entry matches it, the default editor entry is invoked:
```julia
(cmd, path, line, column) -> `$cmd $path`
```
Note that many editors are already defined. All of the following commands should already work:
-   emacs
-   emacsclient
-   vim
-   nvim
-   nano
-   micro
-   kak
-   helix
-   textmate
-   mate
-   kate
-   subl
-   atom
-   notepad++
-   Visual Studio Code
-   open
-   pycharm
-   bbedit
**Examples**
The following defines the usage of terminal-based `emacs`:


# [Interactive Utilities](#man-interactive-utils)
```julia
define_editor(
    r"\bemacs\b.*\s(-nw|--no-window-system)\b", wait=true) do cmd, path, line
    `$cmd +$line $path`
end
```
`define_editor` was introduced in Julia 1.4.
```julia
less(file::AbstractString, [line::Integer])
```
Show a file using the default pager, optionally providing a starting line number. Returns to the `julia` prompt when you quit the pager.
```julia
less(function, [types])
```
Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see.
```julia
@less
```
Evaluates the arguments to the function or macro call, determines their types, and calls the [`less`](#InteractiveUtils.less-Tuple%7BAbstractString%7D) function on the resulting expression.
See also: [`@edit`](#InteractiveUtils.@edit), [`@which`](#InteractiveUtils.@which), [`@code_lowered`](#InteractiveUtils.@code_lowered).
```julia
@which
```
Applied to a function or macro call, it evaluates the arguments to the specified call, and returns the `Method` object for the method that would be called for those arguments. Applied to a variable, it returns the module in which the variable was bound. It calls out to the [`which`](../../base/base/#Base.which-Tuple%7BAny,%20Any%7D) function.
See also: [`@less`](#InteractiveUtils.@less), [`@edit`](#InteractiveUtils.@edit).
```julia
@functionloc
```


# [Interactive Utilities](#man-interactive-utils)
Applied to a function or macro call, it evaluates the arguments to the specified call, and returns a tuple `(filename,line)` giving the location for the method that would be called for those arguments. It calls out to the [`functionloc`](../../base/base/#Base.functionloc-Tuple%7BAny,%20Any%7D) function.
```julia
@code_lowered
```
Evaluates the arguments to the function or macro call, determines their types, and calls [`code_lowered`](../../base/base/#Base.code_lowered) on the resulting expression.
See also: [`code_lowered`](../../base/base/#Base.code_lowered), [`@code_warntype`](#InteractiveUtils.@code_warntype), [`@code_typed`](#InteractiveUtils.@code_typed), [`@code_llvm`](#InteractiveUtils.@code_llvm), [`@code_native`](#InteractiveUtils.@code_native).
```julia
@code_typed
```
Evaluates the arguments to the function or macro call, determines their types, and calls [`code_typed`](../../base/base/#Base.code_typed) on the resulting expression. Use the optional argument `optimize` with
```julia
@code_typed optimize=true foo(x)
```
to control whether additional optimizations, such as inlining, are also applied.
See also: [`code_typed`](../../base/base/#Base.code_typed), [`@code_warntype`](#InteractiveUtils.@code_warntype), [`@code_lowered`](#InteractiveUtils.@code_lowered), [`@code_llvm`](#InteractiveUtils.@code_llvm), [`@code_native`](#InteractiveUtils.@code_native).
```julia
code_warntype([io::IO], f, types; debuginfo=:default)
```


# [Interactive Utilities](#man-interactive-utils)
Prints lowered and type-inferred ASTs for the methods matching the given generic function and type signature to `io` which defaults to `stdout`. The ASTs are annotated in such a way as to cause "non-leaf" types which may be problematic for performance to be emphasized (if color is available, displayed in red). This serves as a warning of potential type instability.
Not all non-leaf types are particularly problematic for performance, and the performance characteristics of a particular type is an implementation detail of the compiler. `code_warntype` will err on the side of coloring types red if they might be a performance concern, so some types may be colored red even if they do not impact performance. Small unions of concrete types are usually not a concern, so these are highlighted in yellow.
Keyword argument `debuginfo` may be one of `:source` or `:none` (default), to specify the verbosity of code comments.
See the [`@code_warntype`](../../manual/performance-tips/#man-code-warntype) section in the Performance Tips page of the manual for more information.
See also: [`@code_warntype`](#InteractiveUtils.@code_warntype), [`code_typed`](../../base/base/#Base.code_typed), [`code_lowered`](../../base/base/#Base.code_lowered), [`code_llvm`](#InteractiveUtils.code_llvm), [`code_native`](#InteractiveUtils.code_native).
```julia
@code_warntype
```
Evaluates the arguments to the function or macro call, determines their types, and calls [`code_warntype`](#InteractiveUtils.code_warntype) on the resulting expression.


# [Interactive Utilities](#man-interactive-utils)
See also: [`code_warntype`](#InteractiveUtils.code_warntype), [`@code_typed`](#InteractiveUtils.@code_typed), [`@code_lowered`](#InteractiveUtils.@code_lowered), [`@code_llvm`](#InteractiveUtils.@code_llvm), [`@code_native`](#InteractiveUtils.@code_native).
```julia
code_llvm([io=stdout,], f, types; raw=false, dump_module=false, optimize=true, debuginfo=:default)
```
Prints the LLVM bitcodes generated for running the method matching the given generic function and type signature to `io`.
If the `optimize` keyword is unset, the code will be shown before LLVM optimizations. All metadata and dbg.\* calls are removed from the printed bitcode. For the full IR, set the `raw` keyword to true. To dump the entire module that encapsulates the function (with declarations), set the `dump_module` keyword to true. Keyword argument `debuginfo` may be one of source (default) or none, to specify the verbosity of code comments.
See also: [`@code_llvm`](#InteractiveUtils.@code_llvm), [`code_warntype`](#InteractiveUtils.code_warntype), [`code_typed`](../../base/base/#Base.code_typed), [`code_lowered`](../../base/base/#Base.code_lowered), [`code_native`](#InteractiveUtils.code_native).
```julia
@code_llvm
```
Evaluates the arguments to the function or macro call, determines their types, and calls [`code_llvm`](#InteractiveUtils.code_llvm) on the resulting expression. Set the optional keyword arguments `raw`, `dump_module`, `debuginfo`, `optimize` by putting them and their value before the function call, like this:


# [Interactive Utilities](#man-interactive-utils)
```julia
@code_llvm raw=true dump_module=true debuginfo=:default f(x)
@code_llvm optimize=false f(x)
```
`optimize` controls whether additional optimizations, such as inlining, are also applied. `raw` makes all metadata and dbg.\* calls visible. `debuginfo` may be one of `:source` (default) or `:none`, to specify the verbosity of code comments. `dump_module` prints the entire module that encapsulates the function.
See also: [`code_llvm`](#InteractiveUtils.code_llvm), [`@code_warntype`](#InteractiveUtils.@code_warntype), [`@code_typed`](#InteractiveUtils.@code_typed), [`@code_lowered`](#InteractiveUtils.@code_lowered), [`@code_native`](#InteractiveUtils.@code_native).
```julia
code_native([io=stdout,], f, types; syntax=:intel, debuginfo=:default, binary=false, dump_module=true)
```
Prints the native assembly instructions generated for running the method matching the given generic function and type signature to `io`.
-   Set assembly syntax by setting `syntax` to `:intel` (default) for intel syntax or `:att` for AT&T syntax.
-   Specify verbosity of code comments by setting `debuginfo` to `:source` (default) or `:none`.
-   If `binary` is `true`, also print the binary machine code for each instruction precedented by an abbreviated address.
-   If `dump_module` is `false`, do not print metadata such as rodata or directives.
-   If `raw` is `false`, uninteresting instructions (like the safepoint function prologue) are elided.


# [Interactive Utilities](#man-interactive-utils)
See also: [`@code_native`](#InteractiveUtils.@code_native), [`code_warntype`](#InteractiveUtils.code_warntype), [`code_typed`](../../base/base/#Base.code_typed), [`code_lowered`](../../base/base/#Base.code_lowered), [`code_llvm`](#InteractiveUtils.code_llvm).
```julia
@code_native
```
Evaluates the arguments to the function or macro call, determines their types, and calls [`code_native`](#InteractiveUtils.code_native) on the resulting expression.
Set any of the optional keyword arguments `syntax`, `debuginfo`, `binary` or `dump_module` by putting it before the function call, like this:
```julia
@code_native syntax=:intel debuginfo=:default binary=true dump_module=false f(x)
```
-   Set assembly syntax by setting `syntax` to `:intel` (default) for Intel syntax or `:att` for AT&T syntax.
-   Specify verbosity of code comments by setting `debuginfo` to `:source` (default) or `:none`.
-   If `binary` is `true`, also print the binary machine code for each instruction precedented by an abbreviated address.
-   If `dump_module` is `false`, do not print metadata such as rodata or directives.
See also: [`code_native`](#InteractiveUtils.code_native), [`@code_warntype`](#InteractiveUtils.@code_warntype), [`@code_typed`](#InteractiveUtils.@code_typed), [`@code_lowered`](#InteractiveUtils.@code_lowered), [`@code_llvm`](#InteractiveUtils.@code_llvm).
```julia
@time_imports
```


# [Interactive Utilities](#man-interactive-utils)
A macro to execute an expression and produce a report of any time spent importing packages and their dependencies. Any compilation time will be reported as a percentage, and how much of which was recompilation, if any.
One line is printed per package or package extension. The duration shown is the time to import that package itself, not including the time to load any of its dependencies.
On Julia 1.9+ [package extensions](../../manual/code-loading/#man-extensions) will show as Parent → Extension.
During the load process a package sequentially imports all of its dependencies, not just its direct dependencies.
```julia-repl
julia> @time_imports using CSV
     50.7 ms  Parsers 17.52% compilation time
      0.2 ms  DataValueInterfaces
      1.6 ms  DataAPI
      0.1 ms  IteratorInterfaceExtensions
      0.1 ms  TableTraits
     17.5 ms  Tables
     26.8 ms  PooledArrays
    193.7 ms  SentinelArrays 75.12% compilation time
      8.6 ms  InlineStrings
     20.3 ms  WeakRefStrings
      2.0 ms  TranscodingStreams
      1.4 ms  Zlib_jll
      1.8 ms  CodecZlib
      0.8 ms  Compat
     13.1 ms  FilePathsBase 28.39% compilation time
   1681.2 ms  CSV 92.40% compilation time
```
This macro requires at least Julia 1.8
```julia
clipboard(x)
```
Send a printed form of `x` to the operating system clipboard ("copy").
```julia
clipboard() -> String
```
Return a string with the contents of the operating system clipboard ("paste").
------------------------------------------------------------------------


# Lazy Artifacts · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/LazyArtifacts/


# [Lazy Artifacts](#Lazy-Artifacts)
In order for a package to download artifacts lazily, `LazyArtifacts` must be explicitly listed as a dependency of that package.
For further information on artifacts, see [Artifacts](../Artifacts/#Artifacts).
------------------------------------------------------------------------


# LibCURL · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/LibCURL/


# [LibCURL](#LibCURL)
This is a simple Julia wrapper around http://curl.haxx.se/libcurl/ generated using [Clang.jl](https://github.com/ihnorton/Clang.jl). Please see the [libcurl API documentation](https://curl.haxx.se/libcurl/c/) for help on how to use this package.
------------------------------------------------------------------------


# LibGit2 · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/LibGit2/


# [LibGit2](#LibGit2)
The LibGit2 module provides bindings to [libgit2](https://libgit2.org/), a portable C library that implements core functionality for the [Git](https://git-scm.com/) version control system. These bindings are currently used to power Julia's package manager. It is expected that this module will eventually be moved into a separate package.


### [Functionality](#Functionality)
Some of this documentation assumes some prior knowledge of the libgit2 API. For more information on some of the objects and methods referenced here, consult the upstream [libgit2 API reference](https://libgit2.org/libgit2/#v1.0.0).
```julia
LibGit2.Buffer
```
A data buffer for exporting data from libgit2. Matches the [`git_buf`](https://libgit2.org/libgit2/#HEAD/type/git_buf) struct.
When fetching data from LibGit2, a typical usage would look like:
```julia
buf_ref = Ref(Buffer())
@check ccall(..., (Ptr{Buffer},), buf_ref)
# operation on buf_ref
free(buf_ref)
```
In particular, note that `LibGit2.free` should be called afterward on the `Ref` object.
```julia
LibGit2.CheckoutOptions
```
Matches the [`git_checkout_options`](https://libgit2.org/libgit2/#HEAD/type/git_checkout_options) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.
-   `checkout_strategy`: determine how to handle conflicts and whether to force the checkout/recreate missing files.
-   `disable_filters`: if nonzero, do not apply filters like CLRF (to convert file newlines between UNIX and DOS).
-   `dir_mode`: read/write/access mode for any directories involved in the checkout. Default is `0755`.
-   `file_mode`: read/write/access mode for any files involved in the checkout. Default is `0755` or `0644`, depending on the blob.
-   `file_open_flags`: bitflags used to open any files during the checkout.
-   `notify_flags`: Flags for what sort of conflicts the user should be notified about.


### [Functionality](#Functionality)
-   `notify_cb`: An optional callback function to notify the user if a checkout conflict occurs. If this function returns a non-zero value, the checkout will be cancelled.
-   `notify_payload`: Payload for the notify callback function.
-   `progress_cb`: An optional callback function to display checkout progress.
-   `progress_payload`: Payload for the progress callback.
-   `paths`: If not empty, describes which paths to search during the checkout. If empty, the checkout will occur over all files in the repository.
-   `baseline`: Expected content of the [`workdir`](#LibGit2.workdir), captured in a (pointer to a) [`GitTree`](#LibGit2.GitTree). Defaults to the state of the tree at HEAD.
-   `baseline_index`: Expected content of the [`workdir`](#LibGit2.workdir), captured in a (pointer to a) `GitIndex`. Defaults to the state of the index at HEAD.
-   `target_directory`: If not empty, checkout to this directory instead of the `workdir`.
-   `ancestor_label`: In case of conflicts, the name of the common ancestor side.
-   `our_label`: In case of conflicts, the name of "our" side.
-   `their_label`: In case of conflicts, the name of "their" side.
-   `perfdata_cb`: An optional callback function to display performance data.
-   `perfdata_payload`: Payload for the performance callback.
```julia
LibGit2.CloneOptions
```
Matches the [`git_clone_options`](https://libgit2.org/libgit2/#HEAD/type/git_clone_options) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.


### [Functionality](#Functionality)
-   `checkout_opts`: The options for performing the checkout of the remote as part of the clone.
-   `fetch_opts`: The options for performing the pre-checkout fetch of the remote as part of the clone.
-   `bare`: If `0`, clone the full remote repository. If non-zero, perform a bare clone, in which there is no local copy of the source files in the repository and the [`gitdir`](#LibGit2.gitdir) and [`workdir`](#LibGit2.workdir) are the same.
-   `localclone`: Flag whether to clone a local object database or do a fetch. The default is to let git decide. It will not use the git-aware transport for a local clone, but will use it for URLs which begin with `file://`.
-   `checkout_branch`: The name of the branch to checkout. If an empty string, the default branch of the remote will be checked out.
-   `repository_cb`: An optional callback which will be used to create the *new* repository into which the clone is made.
-   `repository_cb_payload`: The payload for the repository callback.
-   `remote_cb`: An optional callback used to create the [`GitRemote`](#LibGit2.GitRemote) before making the clone from it.
-   `remote_cb_payload`: The payload for the remote callback.
```julia
LibGit2.DescribeOptions
```
Matches the [`git_describe_options`](https://libgit2.org/libgit2/#HEAD/type/git_describe_options) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.


### [Functionality](#Functionality)
-   `max_candidates_tags`: consider this many most recent tags in `refs/tags` to describe a commit. Defaults to 10 (so that the 10 most recent tags would be examined to see if they describe a commit).
-   `describe_strategy`: whether to consider all entries in `refs/tags` (equivalent to `git-describe --tags`) or all entries in `refs/` (equivalent to `git-describe --all`). The default is to only show annotated tags. If `Consts.DESCRIBE_TAGS` is passed, all tags, annotated or not, will be considered. If `Consts.DESCRIBE_ALL` is passed, any ref in `refs/` will be considered.
-   `pattern`: only consider tags which match `pattern`. Supports glob expansion.
-   `only_follow_first_parent`: when finding the distance from a matching reference to the described object, only consider the distance from the first parent.
-   `show_commit_oid_as_fallback`: if no matching reference can be found which describes a commit, show the commit's [`GitHash`](#LibGit2.GitHash) instead of throwing an error (the default behavior).
```julia
LibGit2.DescribeFormatOptions
```
Matches the [`git_describe_format_options`](https://libgit2.org/libgit2/#HEAD/type/git_describe_format_options) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.
-   `abbreviated_size`: lower bound on the size of the abbreviated `GitHash` to use, defaulting to `7`.
-   `always_use_long_format`: set to `1` to use the long format for strings even if a short format can be used.


### [Functionality](#Functionality)
-   `dirty_suffix`: if set, this will be appended to the end of the description string if the [`workdir`](#LibGit2.workdir) is dirty.
```julia
LibGit2.DiffDelta
```
Description of changes to one entry. Matches the [`git_diff_delta`](https://libgit2.org/libgit2/#HEAD/type/git_diff_delta) struct.
The fields represent:
-   `status`: One of `Consts.DELTA_STATUS`, indicating whether the file has been added/modified/deleted.
-   `flags`: Flags for the delta and the objects on each side. Determines whether to treat the file(s) as binary/text, whether they exist on each side of the diff, and whether the object ids are known to be correct.
-   `similarity`: Used to indicate if a file has been renamed or copied.
-   `nfiles`: The number of files in the delta (for instance, if the delta was run on a submodule commit id, it may contain more than one file).
-   `old_file`: A [`DiffFile`](#LibGit2.DiffFile) containing information about the file(s) before the changes.
-   `new_file`: A [`DiffFile`](#LibGit2.DiffFile) containing information about the file(s) after the changes.
```julia
LibGit2.DiffFile
```
Description of one side of a delta. Matches the [`git_diff_file`](https://libgit2.org/libgit2/#HEAD/type/git_diff_file) struct.
The fields represent:
-   `id`: the [`GitHash`](#LibGit2.GitHash) of the item in the diff. If the item is empty on this side of the diff (for instance, if the diff is of the removal of a file), this will be `GitHash(0)`.
-   `path`: a `NULL` terminated path to the item relative to the working directory of the repository.


### [Functionality](#Functionality)
-   `size`: the size of the item in bytes.
-   `flags`: a combination of the [`git_diff_flag_t`](https://libgit2.org/libgit2/#HEAD/type/git_diff_flag_t) flags. The `i`th bit of this integer sets the `i`th flag.
-   `mode`: the [`stat`](../../base/file/#Base.stat) mode for the item.
-   `id_abbrev`: only present in LibGit2 versions newer than or equal to `0.25.0`. The length of the `id` field when converted using [`string`](../../base/strings/#Base.string). Usually equal to `OID_HEXSZ` (40).
```julia
LibGit2.DiffOptionsStruct
```
Matches the [`git_diff_options`](https://libgit2.org/libgit2/#HEAD/type/git_diff_options) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.
-   `flags`: flags controlling which files will appear in the diff. Defaults to `DIFF_NORMAL`.
-   `ignore_submodules`: whether to look at files in submodules or not. Defaults to `SUBMODULE_IGNORE_UNSPECIFIED`, which means the submodule's configuration will control whether it appears in the diff or not.
-   `pathspec`: path to files to include in the diff. Default is to use all files in the repository.
-   `notify_cb`: optional callback which will notify the user of changes to the diff as file deltas are added to it.
-   `progress_cb`: optional callback which will display diff progress. Only relevant on libgit2 versions at least as new as 0.24.0.
-   `payload`: the payload to pass to `notify_cb` and `progress_cb`.


### [Functionality](#Functionality)
-   `context_lines`: the number of *unchanged* lines used to define the edges of a hunk. This is also the number of lines which will be shown before/after a hunk to provide context. Default is 3.
-   `interhunk_lines`: the maximum number of *unchanged* lines *between* two separate hunks allowed before the hunks will be combined. Default is 0.
-   `id_abbrev`: sets the length of the abbreviated [`GitHash`](#LibGit2.GitHash) to print. Default is `7`.
-   `max_size`: the maximum file size of a blob. Above this size, it will be treated as a binary blob. The default is 512 MB.
-   `old_prefix`: the virtual file directory in which to place old files on one side of the diff. Default is `"a"`.
-   `new_prefix`: the virtual file directory in which to place new files on one side of the diff. Default is `"b"`.
```julia
LibGit2.FetchHead
```
Contains the information about HEAD during a fetch, including the name and URL of the branch fetched from, the oid of the HEAD, and whether the fetched HEAD has been merged locally.
The fields represent:
-   `name`: The name in the local reference database of the fetch head, for example, `"refs/heads/master"`.
-   `url`: The URL of the fetch head.
-   `oid`: The [`GitHash`](#LibGit2.GitHash) of the tip of the fetch head.
-   `ismerge`: Boolean flag indicating whether the changes at the remote have been merged into the local copy yet or not. If `true`, the local copy is up to date with the remote fetch head.
```julia
LibGit2.FetchOptions
```


### [Functionality](#Functionality)
Matches the [`git_fetch_options`](https://libgit2.org/libgit2/#HEAD/type/git_fetch_options) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.
-   `callbacks`: remote callbacks to use during the fetch.
-   `prune`: whether to perform a prune after the fetch or not. The default is to use the setting from the `GitConfig`.
-   `update_fetchhead`: whether to update the [`FetchHead`](#LibGit2.FetchHead) after the fetch. The default is to perform the update, which is the normal git behavior.
-   `download_tags`: whether to download tags present at the remote or not. The default is to request the tags for objects which are being downloaded anyway from the server.
-   `proxy_opts`: options for connecting to the remote through a proxy. See [`ProxyOptions`](#LibGit2.ProxyOptions). Only present on libgit2 versions newer than or equal to 0.25.0.
-   `custom_headers`: any extra headers needed for the fetch. Only present on libgit2 versions newer than or equal to 0.24.0.
```julia
GitAnnotated(repo::GitRepo, commit_id::GitHash)
GitAnnotated(repo::GitRepo, ref::GitReference)
GitAnnotated(repo::GitRepo, fh::FetchHead)
GitAnnotated(repo::GitRepo, committish::AbstractString)
```


### [Functionality](#Functionality)
An annotated git commit carries with it information about how it was looked up and why, so that rebase or merge operations have more information about the context of the commit. Conflict files contain information about the source/target branches in the merge which are conflicting, for instance. An annotated commit can refer to the tip of a remote branch, for instance when a [`FetchHead`](#LibGit2.FetchHead) is passed, or to a branch head described using `GitReference`.
```julia
GitBlame(repo::GitRepo, path::AbstractString; options::BlameOptions=BlameOptions())
```
Construct a `GitBlame` object for the file at `path`, using change information gleaned from the history of `repo`. The `GitBlame` object records who changed which chunks of the file when, and how. `options` controls how to separate the contents of the file and which commits to probe - see [`BlameOptions`](#LibGit2.BlameOptions) for more information.
```julia
GitBlob(repo::GitRepo, hash::AbstractGitHash)
GitBlob(repo::GitRepo, spec::AbstractString)
```
Return a `GitBlob` object from `repo` specified by `hash`/`spec`.
-   `hash` is a full (`GitHash`) or partial (`GitShortHash`) hash.
-   `spec` is a textual specification: see [the git docs](https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions) for a full list.
```julia
GitCommit(repo::GitRepo, hash::AbstractGitHash)
GitCommit(repo::GitRepo, spec::AbstractString)
```
Return a `GitCommit` object from `repo` specified by `hash`/`spec`.
-   `hash` is a full (`GitHash`) or partial (`GitShortHash`) hash.


### [Functionality](#Functionality)
-   `spec` is a textual specification: see [the git docs](https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions) for a full list.
```julia
GitConfig(path::AbstractString, level::Consts.GIT_CONFIG=Consts.CONFIG_LEVEL_APP, force::Bool=false)
```
Create a new `GitConfig` by loading configuration information from the file at `path`. See [`addfile`](#LibGit2.addfile) for more information about the `level`, `repo` and `force` options.
```julia
GitConfig(repo::GitRepo)
```
Get the stored configuration for the git repository `repo`. If `repo` does not have a specific configuration file set, the default git configuration will be used.
```julia
GitConfig(level::Consts.GIT_CONFIG=Consts.CONFIG_LEVEL_DEFAULT)
```
Get the default git configuration by loading the global and system configuration files into a prioritized configuration. This can be used to access default configuration options outside a specific git repository.
```julia
GitHash
```
A git object identifier, based on the sha-1 hash. It is a 20 byte string (40 hex digits) used to identify a `GitObject` in a repository.
```julia
GitObject(repo::GitRepo, hash::AbstractGitHash)
GitObject(repo::GitRepo, spec::AbstractString)
```
Return the specified object ([`GitCommit`](#LibGit2.GitCommit), [`GitBlob`](#LibGit2.GitBlob), [`GitTree`](#LibGit2.GitTree) or [`GitTag`](#LibGit2.GitTag)) from `repo` specified by `hash`/`spec`.
-   `hash` is a full (`GitHash`) or partial (`GitShortHash`) hash.


### [Functionality](#Functionality)
-   `spec` is a textual specification: see [the git docs](https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions) for a full list.
```julia
GitRemote(repo::GitRepo, rmt_name::AbstractString, rmt_url::AbstractString) -> GitRemote
```
Look up a remote git repository using its name and URL. Uses the default fetch refspec.
**Examples**
```julia
repo = LibGit2.init(repo_path)
remote = LibGit2.GitRemote(repo, "upstream", repo_url)
```
```julia
GitRemote(repo::GitRepo, rmt_name::AbstractString, rmt_url::AbstractString, fetch_spec::AbstractString) -> GitRemote
```
Look up a remote git repository using the repository's name and URL, as well as specifications for how to fetch from the remote (e.g. which remote branch to fetch from).
**Examples**
```julia
repo = LibGit2.init(repo_path)
refspec = "+refs/heads/mybranch:refs/remotes/origin/mybranch"
remote = LibGit2.GitRemote(repo, "upstream", repo_url, refspec)
```
```julia
GitRemoteAnon(repo::GitRepo, url::AbstractString) -> GitRemote
```
Look up a remote git repository using only its URL, not its name.
**Examples**
```julia
repo = LibGit2.init(repo_path)
remote = LibGit2.GitRemoteAnon(repo, repo_url)
```
```julia
LibGit2.GitRepo(path::AbstractString)
```
Open a git repository at `path`.
```julia
LibGit2.GitRepoExt(path::AbstractString, flags::Cuint = Cuint(Consts.REPOSITORY_OPEN_DEFAULT))
```
Open a git repository at `path` with extended controls (for instance, if the current user must be a member of a special access group to read `path`).
```julia
GitRevWalker(repo::GitRepo)
```


### [Functionality](#Functionality)
A `GitRevWalker` *walks* through the *revisions* (i.e. commits) of a git repository `repo`. It is a collection of the commits in the repository, and supports iteration and calls to [`LibGit2.map`](#LibGit2.map) and [`LibGit2.count`](#LibGit2.count) (for instance, `LibGit2.count` could be used to determine what percentage of commits in a repository were made by a certain author).
```julia
cnt = LibGit2.with(LibGit2.GitRevWalker(repo)) do walker
    LibGit2.count((oid,repo)->(oid == commit_oid1), walker, oid=commit_oid1, by=LibGit2.Consts.SORT_TIME)
end
```
Here, `LibGit2.count` finds the number of commits along the walk with a certain `GitHash`. Since the `GitHash` is unique to a commit, `cnt` will be `1`.
```julia
GitShortHash(hash::GitHash, len::Integer)
```
A shortened git object identifier, which can be used to identify a git object when it is unique, consisting of the initial `len` hexadecimal digits of `hash` (the remaining digits are ignored).
```julia
LibGit2.GitSignature
```
This is a Julia wrapper around a pointer to a [`git_signature`](https://libgit2.org/libgit2/#HEAD/type/git_signature) object.
```julia
LibGit2.GitStatus(repo::GitRepo; status_opts=StatusOptions())
```
Collect information about the status of each file in the git repository `repo` (e.g. is the file modified, staged, etc.). `status_opts` can be used to set various options, for instance whether or not to look at untracked files or whether to include submodules or not. See [`StatusOptions`](#LibGit2.StatusOptions) for more information.


### [Functionality](#Functionality)
```julia
GitTag(repo::GitRepo, hash::AbstractGitHash)
GitTag(repo::GitRepo, spec::AbstractString)
```
Return a `GitTag` object from `repo` specified by `hash`/`spec`.
-   `hash` is a full (`GitHash`) or partial (`GitShortHash`) hash.
-   `spec` is a textual specification: see [the git docs](https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions) for a full list.
```julia
GitTree(repo::GitRepo, hash::AbstractGitHash)
GitTree(repo::GitRepo, spec::AbstractString)
```
Return a `GitTree` object from `repo` specified by `hash`/`spec`.
-   `hash` is a full (`GitHash`) or partial (`GitShortHash`) hash.
-   `spec` is a textual specification: see [the git docs](https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions) for a full list.
```julia
LibGit2.IndexEntry
```
In-memory representation of a file entry in the index. Matches the [`git_index_entry`](https://libgit2.org/libgit2/#HEAD/type/git_index_entry) struct.
```julia
LibGit2.IndexTime
```
Matches the [`git_index_time`](https://libgit2.org/libgit2/#HEAD/type/git_index_time) struct.
```julia
LibGit2.BlameOptions
```
Matches the [`git_blame_options`](https://libgit2.org/libgit2/#HEAD/type/git_blame_options) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.
-   `flags`: one of `Consts.BLAME_NORMAL` or `Consts.BLAME_FIRST_PARENT` (the other blame flags are not yet implemented by libgit2).


### [Functionality](#Functionality)
-   `min_match_characters`: the minimum number of *alphanumeric* characters which much change in a commit in order for the change to be associated with that commit. The default is 20. Only takes effect if one of the `Consts.BLAME_*_COPIES` flags are used, which libgit2 does not implement yet.
-   `newest_commit`: the [`GitHash`](#LibGit2.GitHash) of the newest commit from which to look at changes.
-   `oldest_commit`: the [`GitHash`](#LibGit2.GitHash) of the oldest commit from which to look at changes.
-   `min_line`: the first line of the file from which to starting blaming. The default is `1`.
-   `max_line`: the last line of the file to which to blame. The default is `0`, meaning the last line of the file.
```julia
LibGit2.MergeOptions
```
Matches the [`git_merge_options`](https://libgit2.org/libgit2/#HEAD/type/git_merge_options) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.
-   `flags`: an `enum` for flags describing merge behavior. Defined in [`git_merge_flag_t`](https://github.com/libgit2/libgit2/blob/HEAD/include/git2/merge.h#L95). The corresponding Julia enum is `GIT_MERGE` and has values:
    -   `MERGE_FIND_RENAMES`: detect if a file has been renamed between the common ancestor and the "ours" or "theirs" side of the merge. Allows merges where a file has been renamed.
    -   `MERGE_FAIL_ON_CONFLICT`: exit immediately if a conflict is found rather than trying to resolve it.