Update some function sigs for tasks and events, clear out HelpDB (#17846

)

base/docs/helpdb/Base.jl

@@ -54,18 +54,6 @@ Subtype operator, equivalent to `issubtype(T1,T2)`.
 """
 Base.:(<:)
 
-"""
-    schedule(t::Task, [val]; error=false)
-
-Add a task to the scheduler's queue. This causes the task to run constantly when the system
-is otherwise idle, unless the task performs a blocking operation such as `wait`.
-
-If a second argument is provided, it will be passed to the task (via the return value of
-`yieldto`) when it runs again. If `error` is `true`, the value is raised as an exception in
-the woken task.
-"""
-schedule
-
 """
     takebuf_array(b::IOBuffer)
 
@@ -258,29 +246,6 @@ Returns `true` if `path` is a regular file, `false` otherwise.
 """
 isfile
 
-"""
-    task_local_storage(symbol)
-
-Look up the value of a symbol in the current task's task-local storage.
-"""
-task_local_storage(symbol)
-
-"""
-    task_local_storage(symbol, value)
-
-Assign a value to a symbol in the current task's task-local storage.
-"""
-task_local_storage(symbol, value)
-
-"""
-    task_local_storage(body, symbol, value)
-
-Call the function `body` with a modified task-local storage, in which `value` is assigned to
-`symbol`; the previous value of `symbol`, or lack thereof, is restored afterwards. Useful
-for emulating dynamic scoping.
-"""
-task_local_storage(body, symbol, value)
-
 """
     diff(A, [dim])
 
@@ -1107,13 +1072,6 @@ Convert all arguments to their common promotion type (if any), and return them a
 """
 promote
 
-"""
-    @schedule
-
-Wrap an expression in a `Task` and add it to the local machine's scheduler queue.
-"""
-:@schedule
-
 """
     gradient(F, [h])
 
@@ -1465,15 +1423,6 @@ Dict{String,Float64} with 3 entries:
 """
 merge
 
-"""
-    yield()
-
-Switch to the scheduler to allow another scheduled task to run. A task that calls this
-function is still runnable, and will be restarted immediately if there are no other runnable
-tasks.
-"""
-yield
-
 """
     transpose!(dest,src)
 
@@ -2215,14 +2164,6 @@ Compute the LU factorization of `A`, such that `A[p,:] = L*U`.
 """
 lu
 
-"""
-    @task
-
-Wrap an expression in a `Task` without executing it, and return the `Task`. This only
-creates a task, and does not run it.
-"""
-:@task
-
 """
     fld(x, y)
 
@@ -2770,16 +2711,6 @@ Compute the inverse error function of a real `x`, defined by ``\\operatorname{er
 """
 erfinv
 
-"""
-    @async
-
-Like `@schedule`, `@async` wraps an expression in a `Task` and adds it to the local
-machine's scheduler queue. Additionally it adds the task to the set of items that the
-nearest enclosing `@sync` waits for. `@async` also wraps the expression in a `let x=x, y=y, ...`
-block to create a new scope with copies of all variables referenced in the expression.
-"""
-:@async
-
 """
     readdir([dir]) -> Vector{String}
 
@@ -4041,13 +3972,6 @@ Like `selectperm`, but accepts a preallocated index vector `ix`. If `initialized
 """
 selectperm!
 
-"""
-    istaskdone(task) -> Bool
-
-Tell whether a task has exited.
-"""
-istaskdone
-
 """
     .>(x, y)
 
@@ -4187,15 +4111,6 @@ Determine whether a stream is read-only.
 """
 isreadonly
 
-"""
-    notify(condition, val=nothing; all=true, error=false)
-
-Wake up tasks waiting for a condition, passing them `val`. If `all` is `true` (the default),
-all waiting tasks are woken, otherwise only one is. If `error` is `true`, the passed value
-is raised as an exception in the woken tasks.
-"""
-notify
-
 """
     view(A, inds...)
 
@@ -4868,15 +4783,6 @@ Type conversion cannot be done exactly.
 """
 InexactError
 
-"""
-    @sync
-
-Wait until all dynamically-enclosed uses of `@async`, `@spawn`, `@spawnat` and `@parallel`
-are complete. All exceptions thrown by enclosed async operations are collected and thrown as
-a `CompositeException`.
-"""
-:@sync
-
 """
     typemax(T)
 
@@ -6723,18 +6629,6 @@ base64-encoded string.
 """
 base64encode
 
-"""
-    Condition()
-
-Create an edge-triggered event source that tasks can wait for. Tasks that call `wait` on a
-`Condition` are suspended and queued. Tasks are woken up when `notify` is later called on
-the `Condition`. Edge triggering means that only tasks waiting at the time `notify` is
-called can be woken up. For level-triggered notifications, you must keep extra state to keep
-track of whether a notification has happened. The `Channel` type does this, and so can be
-used for level-triggered events.
-"""
-Condition
-
 """
     filt!(out, b, a, x, [si])
 
@@ -7912,16 +7806,6 @@ Bitwise or.
 """
 Base.:(|)
 
-"""
-    yieldto(task, arg = nothing)
-
-Switch to the given task. The first time a task is switched to, the task's function is
-called with no arguments. On subsequent switches, `arg` is returned from the task's last
-call to `yieldto`. This is a low-level call that only switches tasks, not considering states
-or scheduling in any way. Its use is discouraged.
-"""
-yieldto
-
 """
     readandwrite(command)
 
@@ -8072,13 +7956,6 @@ Compute the Dawson function (scaled imaginary error function) of `x`, defined by
 """
 dawson
 
-"""
-    current_task()
-
-Get the currently running `Task`.
-"""
-current_task
-
 """
     randjump(r::MersenneTwister, jumps, [jumppoly]) -> Vector{MersenneTwister}
 

base/event.jl

@@ -2,6 +2,16 @@
 
 ## condition variables
 
+"""
+    Condition()
+
+Create an edge-triggered event source that tasks can wait for. Tasks that call `wait` on a
+`Condition` are suspended and queued. Tasks are woken up when `notify` is later called on
+the `Condition`. Edge triggering means that only tasks waiting at the time `notify` is
+called can be woken up. For level-triggered notifications, you must keep extra state to keep
+track of whether a notification has happened. The [`Channel`](:class:`Channel`) type does
+this, and so can be used for level-triggered events.
+"""
 type Condition
     waitq::Vector{Any}
 
@@ -21,6 +31,13 @@ function wait(c::Condition)
     end
 end
 
+"""
+    notify(condition, val=nothing; all=true, error=false)
+
+Wake up tasks waiting for a condition, passing them `val`. If `all` is `true` (the default),
+all waiting tasks are woken, otherwise only one is. If `error` is `true`, the passed value
+is raised as an exception in the woken tasks.
+"""
 notify(c::Condition, arg::ANY=nothing; all=true, error=false) = notify(c, arg, all, error)
 function notify(c::Condition, arg, all, error)
     if all
@@ -42,6 +59,11 @@ notify1_error(c::Condition, err) = notify(c, err, error=true, all=false)
 
 
 # schedule an expression to run asynchronously, with minimal ceremony
+"""
+    @schedule
+
+Wrap an expression in a `Task` and add it to the local machine's scheduler queue.
+"""
 macro schedule(expr)
     expr = :(()->($expr))
     :(enq_work(Task($(esc(expr)))))
@@ -61,6 +83,16 @@ end
 
 schedule(t::Task) = enq_work(t)
 
+"""
+    schedule(t::Task, [val]; error=false)
+
+Add a task to the scheduler's queue. This causes the task to run constantly when the system
+is otherwise idle, unless the task performs a blocking operation such as `wait`.
+
+If a second argument `val` is provided, it will be passed to the task (via the return value of
+`yieldto`) when it runs again. If `error` is `true`, the value is raised as an exception in
+the woken task.
+"""
 function schedule(t::Task, arg; error=false)
     # schedule a task to be (re)started with the given value or exception
     if error
@@ -84,8 +116,23 @@ function schedule_and_wait(t::Task, v=nothing)
     return wait()
 end
 
+"""
+    yield()
+
+Switch to the scheduler to allow another scheduled task to run. A task that calls this
+function is still runnable, and will be restarted immediately if there are no other runnable
+tasks.
+"""
 yield() = (enq_work(current_task()); wait())
 
+"""
+    yieldto(task, arg = nothing)
+
+Switch to the given task. The first time a task is switched to, the task's function is
+called with no arguments. On subsequent switches, `arg` is returned from the task's last
+call to `yieldto`. This is a low-level call that only switches tasks, not considering states
+or scheduling in any way. Its use is discouraged.
+"""
 yieldto(t::Task, x::ANY = nothing) = ccall(:jl_switchto, Any, (Any, Any), t, x)
 
 # yield to a task, throwing an exception in it

base/task.jl

@@ -50,17 +50,34 @@ function show(io::IO, t::Task)
     print(io, "Task ($(t.state)) @0x$(hex(convert(UInt, pointer_from_objref(t)), Sys.WORD_SIZE>>2))")
 end
 
+"""
+    @task
+
+Wrap an expression in a [`Task`](:class:`Task`) without executing it, and return the [`Task`](:class:`Task`). This only
+creates a task, and does not run it.
+"""
 macro task(ex)
     :(Task(()->$(esc(ex))))
 end
 
+"""
+    current_task()
+
+Get the currently running [`Task`](:class:`Task`).
+"""
 current_task() = ccall(:jl_get_current_task, Ref{Task}, ())
+
+"""
+    istaskdone(task) -> Bool
+
+Determine whether a task has exited.
+"""
 istaskdone(t::Task) = ((t.state == :done) | (t.state == :failed))
 
 """
     istaskstarted(task) -> Bool
 
-Tell whether a task has started executing.
+Determine whether a task has started executing.
 """
 istaskstarted(t::Task) = ccall(:jl_is_task_started, Cint, (Any,), t) != 0
 
@@ -71,9 +88,28 @@ function get_task_tls(t::Task)
     end
     (t.storage)::ObjectIdDict
 end
+
+"""
+    task_local_storage(key)
+
+Look up the value of a key in the current task's task-local storage.
+"""
 task_local_storage(key) = task_local_storage()[key]
+
+"""
+    task_local_storage(key, value)
+
+Assign a value to a key in the current task's task-local storage.
+"""
 task_local_storage(key, val) = (task_local_storage()[key] = val)
 
+"""
+    task_local_storage(body, key, value)
+
+Call the function `body` with a modified task-local storage, in which `value` is assigned to
+`key`; the previous value of `key`, or lack thereof, is restored afterwards. Useful
+for emulating dynamic scoping.
+"""
 function task_local_storage(body::Function, key, val)
     tls = task_local_storage()
     hadkey = haskey(tls,key)
@@ -277,6 +313,13 @@ function sync_end()
     nothing
 end
 
+"""
+    @sync
+
+Wait until all dynamically-enclosed uses of `@async`, `@spawn`, `@spawnat` and `@parallel`
+are complete. All exceptions thrown by enclosed async operations are collected and thrown as
+a `CompositeException`.
+"""
 macro sync(block)
     quote
         sync_begin()
@@ -305,6 +348,14 @@ function async_run_thunk(thunk)
     t
 end
 
+"""
+    @async
+
+Like `@schedule`, `@async` wraps an expression in a `Task` and adds it to the local
+machine's scheduler queue. Additionally it adds the task to the set of items that the
+nearest enclosing `@sync` waits for. `@async` also wraps the expression in a `let x=x, y=y, ...`
+block to create a new scope with copies of all variables referenced in the expression.
+"""
 macro async(expr)
     expr = localize_vars(esc(:(()->($expr))), false)
     :(async_run_thunk($expr))