Skip to content

Commit

Permalink
Update some function sigs for tasks and events, clear out HelpDB (#17846
Browse files Browse the repository at this point in the history
)
  • Loading branch information
kshyatt authored Aug 7, 2016
1 parent ed125e9 commit 6ba3b97
Show file tree
Hide file tree
Showing 4 changed files with 111 additions and 136 deletions.
123 changes: 0 additions & 123 deletions base/docs/helpdb/Base.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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])
Expand Down Expand Up @@ -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])
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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...)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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])
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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}
Expand Down
47 changes: 47 additions & 0 deletions base/event.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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}

Expand All @@ -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
Expand 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)))))
Expand All @@ -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
Expand All @@ -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
Expand Down
53 changes: 52 additions & 1 deletion base/task.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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))
Expand Down
Loading

0 comments on commit 6ba3b97

Please sign in to comment.