Background work
.
A command runs between two messages, and the window cannot draw until it ends. So a command must be quick. Work that takes a while, such as a large file, a network request or a long computation, belongs on another thread.
The pattern has two halves, and you have seen both: a command
starts
the work and returns at once, and the result comes back through a port.
Search
The worker is at 40 percent. The window stays responsive, and Cancel works. A Silk program has no threads in a page yet, so this example is shown in pictures.
The worker is at 40 percent. The window stays responsive, and Cancel works. A Silk program has no threads in a page yet, so this example is shown in pictures.
The worker posted its answer.
The worker posted its answer.
The program counts the primes below five million. That takes a few seconds, and the window never stops responding.
examples/src/native/search.silk
Copy
//! Search: slow work on another thread. A command starts it and returns at once, and the
//! worker posts its progress and its answer to ports the program subscribes to.
import
core.look {
INK
,
MUTED
, button, primary, rgb }
import
loom.css
import
loom.css { px,
Align
}
import
loom.lib {
CommandSet
,
Document
,
Node
,
NoOutput
,
Program
,
Subscriptions
,
Update
}
import
silk.mem.allocator {
Allocator
,
OutOfMemoryError
}
import
silk.text.string {
String
}
/// The ports the worker posts to.
pub
const
PORT_PROGRESS
: string =
"search:progress"
pub
const
PORT_DONE
: string =
"search:done"
/// Work that takes a while. The app's `Worker` runs it on a thread; a test's answers at once.
pub
service
Worker
{
/// Starts counting the primes below `limit` and returns without waiting. Progress, in
/// percent, is posted to `PORT_PROGRESS` and the count to `PORT_DONE`.
effect
fn
countPrimes
(limit: u32) -> () !
OutOfMemoryError
? &
mut
Worker
| &
mut
Allocator
/// Asks the work that is running to stop.
effect
fn
cancel
() -> () ? &
mut
Worker
}
pub
struct
Search
{
pub
running: bool,
/// How far the work is, in text: "40".
pub
progress:
String
,
/// The answer, in text; empty until there is one.
pub
found:
String
, }
pub
union
Message
{
ClickedStart
,
ClickedCancel
,
StartedWork
,
GotProgress
{
pub
percent:
String
},
GotAnswer
{
pub
count:
String
}, }
pub
union
Command
{
Start
{
pub
limit: u32 },
Cancel
, }
impl
CommandSet
<
Message
? &
mut
Worker
| &
mut
Allocator
>
for
Command
{
effect
fn
execute
(self:
Self
) ->
Message
!
OutOfMemoryError
? &
mut
Worker
| &
mut
Allocator
{
match
move
self {
Command
.
Start
{ limit } => {
run
Worker
.
countPrimes
(limit) }
Command
.
Cancel
=> {
run
Worker
.
cancel
() } }
return
Message
.
StartedWork
} }
type
Next
=
Update
<
Search
,
Command
,
NoOutput
>
impl
Program
<
Message
,
Command
>
for
Search
{
effect
fn
init
() ->
Next
!
OutOfMemoryError
? &
mut
Allocator
{
return
Next
.
of
(
Search
{ running:
false
, progress:
String
.
make
(), found:
String
.
make
() }) }
effect
fn
update
(
mut
model:
Search
, message:
Message
) ->
Next
!
OutOfMemoryError
? &
mut
Allocator
{
match
move
message {
Message
.
ClickedStart
=> { model.running =
true
model.progress =
run
String
.
copy
(
"0"
) model.found =
String
.
make
()
return
run
Next
.
with
(
move
model,
Command
.
Start
{ limit:
5000000
}) }
Message
.
ClickedCancel
=> { model.running =
false
return
run
Next
.
with
(
move
model,
Command
.
Cancel
) }
Message
.
StartedWork
=> {}
Message
.
GotProgress
{ percent } => {
// A worker that was cancelled may still have a post on its way.
if
model.running { model.progress =
move
percent } }
Message
.
GotAnswer
{ count } => {
if
model.running { model.running =
false
model.found =
move
count } } }
return
Next
.
of
(
move
model) }
fn
view
(model: &
Search
, h: &
Document
<
Message
>) ->
Node
{
return
h.
column
( &[h.
style
(&[css.
padding
(
px
(
20.0
)), css.
rowGap
(
px
(
12.0
)), css.
color
(
rgb
(
INK
))])], &[ h.
text
(
"How many primes are there below five million?"
), h.
row
( &[h.
style
(&[css.
alignItems
(
Align
.
Center
), css.
columnGap
(
px
(
10.0
))])], &[
if
model.running {
button
(h,
"Cancel"
,
Message
.
ClickedCancel
) }
else
{
primary
(h,
"Count them"
,
Message
.
ClickedStart
) },
if
model.running { h.
row
( &[h.
testId
(
"progress"
), h.
style
(&[css.
color
(
rgb
(
MUTED
))])], &[h.
text
(
String
.
view
(&model.progress)), h.
text
(
"%"
)], ) }
else
{ h.
empty
() }, ], ),
if
String
.
byteLength
(
String
.
view
(&model.found)) !=
0
{ h.
row
( &[h.
testId
(
"found"
), h.
style
(&[css.
fontWeight
(
700.0
)])], &[h.
text
(
String
.
view
(&model.found)), h.
text
(
" primes"
)], ) }
else
{ h.
empty
() }, ], ) }
fn
subscriptions
(model: &
Search
, subs: &
mut
Subscriptions
<
Message
>) -> () { subs.
port
(
1
,
PORT_PROGRESS
, |text|
Message
.
GotProgress
{ percent:
move
text }) subs.
port
(
2
,
PORT_DONE
, |text|
Message
.
GotAnswer
{ count:
move
text }) } }
The program's side
The program knows nothing about threads. It has a service that starts work:
examples/src/native/search.silk
Copy
/// Work that takes a while. The app's `Worker` runs it on a thread; a test's answers at once.
pub
service
Worker
{
/// Starts counting the primes below `limit` and returns without waiting. Progress, in
/// percent, is posted to `PORT_PROGRESS` and the count to `PORT_DONE`.
effect
fn
countPrimes
(limit: u32) -> () !
OutOfMemoryError
? &
mut
Worker
| &
mut
Allocator
/// Asks the work that is running to stop.
effect
fn
cancel
() -> () ? &
mut
Worker
}
And two ports where results arrive:
examples/src/native/search.silk
Copy
fn
subscriptions
(model: &
Search
, subs: &
mut
Subscriptions
<
Message
>) -> () { subs.
port
(
1
,
PORT_PROGRESS
, |text|
Message
.
GotProgress
{ percent:
move
text }) subs.
port
(
2
,
PORT_DONE
, |text|
Message
.
GotAnswer
{ count:
move
text }) }
Between the two,
update
is ordinary.
ClickedStart
returns a command. Some time later
GotProgress
messages arrive, and finally
GotAnswer
.
Late answers
examples/src/native/search.silk
Copy
effect
fn
update
(
mut
model:
Search
, message:
Message
) ->
Next
!
OutOfMemoryError
? &
mut
Allocator
{
match
move
message {
Message
.
ClickedStart
=> { model.running =
true
model.progress =
run
String
.
copy
(
"0"
) model.found =
String
.
make
()
return
run
Next
.
with
(
move
model,
Command
.
Start
{ limit:
5000000
}) }
Message
.
ClickedCancel
=> { model.running =
false
return
run
Next
.
with
(
move
model,
Command
.
Cancel
) }
Message
.
StartedWork
=> {}
Message
.
GotProgress
{ percent } => {
// A worker that was cancelled may still have a post on its way.
if
model.running { model.progress =
move
percent } }
Message
.
GotAnswer
{ count } => {
if
model.running { model.running =
false
model.found =
move
count } } }
return
Next
.
of
(
move
model) }
A worker that was told to stop may already have posted something. The program has to expect that, and it does so with plain state: progress and answers only count while
model.running
is true.
This is worth copying. A message from the outside can always arrive later than you would like.
The app's side
examples/apps/search/src/main.silk
Copy
//! Search in a native window. The `Worker` the program's commands ask for is here: it counts
//! on a thread and posts to the program's ports.
import
examples.native.search {
Command
,
Message
,
PORT_DONE
,
PORT_PROGRESS
,
Search
,
Worker
}
import
loom_window.background {
Background
,
Cancellation
}
import
loom_window.program {
Launched
,
Poster
,
Window
, failed, launch, show, systemFonts }
import
silk.collections.bytes {
Bytes
}
import
silk.collections.slice {
Slice
}
import
silk.core.
effect
{
Effect
}
import
silk.core.option {
Option
}
import
silk.core.result {
Result
}
import
silk.mem.allocator {
Allocator
,
OutOfMemoryError
}
import
silk.num.u32
import
silk.text.string {
InvalidUtf8
,
String
}
/// `value` in decimal.
fn
decimal
(value: u32) ->
String
{
let
mut
allocator =
Allocator
.
systemAllocatorProvider
()
let
mut
digits: [u8;
10
] = [
0
;
10
]
let
mut
count: usize =
0
let
mut
rest = value
while
count ==
0
|| rest >
0
{ digits[count] = u32.
toU8
(rest %
10
) +
48
rest = rest /
10
count = count +
1
}
let
mut
bytes =
Bytes
.
make
()
while
count >
0
{ count = count -
1
run
Effect
.
catchAll
(bytes.
append
(
Slice
.view<u8>(&digits, count,
1
)), ignored) |>
Effect
.provideMut<
Allocator
>(&
mut
allocator) }
return
String
.
fromBytes
(
move
bytes) |>
Result
<
String
,
InvalidUtf8
>.
unwrapOr
(
String
.
make
()) }
effect
fn
ignored<
E
>(error:
E
) -> () {
drop
error }
fn
isPrime
(value: u32) -> bool {
if
value <
2
{
return
false
}
let
mut
divisor: u32 =
2
while
divisor * divisor <= value {
if
value % divisor ==
0
{
return
false
} divisor = divisor +
1
}
return
true
}
/// The work itself. It runs on the worker thread and owns everything it touches.
fn
count
(limit: u32, poster:
Poster
, cancellation:
Cancellation
) -> () {
let
step = limit /
100
let
mut
found: u32 =
0
let
mut
value: u32 =
0
while
value < limit {
if
isPrime
(value) { found = found +
1
} value = value +
1
if
step !=
0
&& value % step ==
0
{
if
cancellation.
cancelled
() {
return
() }
// A post wakes the window's loop: `subs.port` hears it on the UI thread.
poster.
post
(
PORT_PROGRESS
,
String
.
view
(&
decimal
(value / step))) } } poster.
post
(
PORT_DONE
,
String
.
view
(&
decimal
(found))) }
/// The worker of this app: one job at a time.
struct
Threads
{ poster:
Poster
, job:
Option
<
Background
<()>>, cancellation:
Option
<
Cancellation
>, }
effect
fn
unstarted<
E
>(error:
E
) ->
Option
<
Background
<()>> {
drop
error
return
Option
<
Background
<()>>.
None
}
effect
fn
started
(job:
Background
<()>) ->
Option
<
Background
<()>> {
return
Option
<
Background
<()>>.
some
(
move
job) }
impl
Threads
{
/// Tells the job that is running, if any, to stop.
fn
stop
(self: &
Self
) -> () {
if
let
Option
<
Cancellation
>.
Some
{ value } = &self.cancellation { value.
cancel
() } } }
impl
Worker
for
Threads
{
effect
fn
countPrimes
(self: &
mut
Self
, limit: u32) -> () !
OutOfMemoryError
? &
mut
Allocator
{ self.
stop
()
let
poster = self.poster.
clone
()
let
cancellation =
run
Cancellation
.
make
()
let
seen = cancellation.
clone
() self.cancellation =
Option
<
Cancellation
>.
some
(
move
cancellation)
// Dropping the job before this one waits for it, and it was just told to stop.
self.job =
run
Effect
.
catchAll
(
Effect
.
flatMap
(
Background
<()>.
start
( || -> () {
count
(limit,
move
poster,
move
seen) }, ), started, ), unstarted, ) }
effect
fn
cancel
(self: &
mut
Self
) -> () { self.
stop
() } }
effect
fn
search
(platform:
Option
<
Launched
>) -> i32 !
OutOfMemoryError
? &
mut
Allocator
{
let
mut
window =
run
Window
.
make
(
"Search"
,
420.0
,
200.0
)
let
mut
threads =
Threads
{ poster: window.
poster
(), job:
Option
<
Background
<()>>.
None
, cancellation:
Option
<
Cancellation
>.
None
, }
let
fonts =
run
systemFonts
()
return
run
show<
Search
,
Message
,
Command
, &
mut
Worker
| &
mut
Allocator
>(
move
window, &fonts,
move
platform, ) |>
Effect
.provideMut<
Worker
>(&
mut
threads) }
fn
app
(platform:
Option
<
Launched
>) -> i32 {
let
mut
allocator =
Allocator
.
systemAllocatorProvider
()
return
run
Effect
.
catchAll
(
search
(
move
platform), failed) |>
Effect
.provideMut<
Allocator
>(&
mut
allocator) }
pub
fn
main
() -> i32 {
return
launch
( |platform:
Option
<
Launched
>| -> i32 {
return
app
(
move
platform) }, ) }
This is where the thread is.
•
window.poster()
is a handle that posts to the program's ports
from any thread
. The window's loop wakes up and
subs.port
delivers the text as a message on the UI thread.
•
Background<()>.start(work)
runs a function on a new thread.
•
Cancellation
is a flag both threads can see. The worker checks it now and then and stops when it is set.
examples/apps/search/src/main.silk
Copy
/// The work itself. It runs on the worker thread and owns everything it touches.
fn
count
(limit: u32, poster:
Poster
, cancellation:
Cancellation
) -> () {
let
step = limit /
100
let
mut
found: u32 =
0
let
mut
value: u32 =
0
while
value < limit {
if
isPrime
(value) { found = found +
1
} value = value +
1
if
step !=
0
&& value % step ==
0
{
if
cancellation.
cancelled
() {
return
() }
// A post wakes the window's loop: `subs.port` hears it on the UI thread.
poster.
post
(
PORT_PROGRESS
,
String
.
view
(&
decimal
(value / step))) } } poster.
post
(
PORT_DONE
,
String
.
view
(&
decimal
(found))) }
The work is a plain function. It owns everything it touches: the limit, its own copy of the poster, and the cancellation flag. It shares nothing with the UI thread except through the poster.
Ports carry text, so the worker posts its numbers as text and the program shows them as they are.
Shell
Copy
silk task native demo docs/examples/apps/search
Why it is built this way
There is no shared state to lock, because the only way into the program is a message. The model is only ever touched by
update
, on one thread.
And the program is still testable. A test provides a
Worker
that does nothing and posts to the ports itself:
tests/src/native.silk
Copy
/// A worker that only counts how often it was asked.
struct
Counted
{ started: u32, cancelled: u32, }
tests/src/native.silk
Copy
effect
fn
searchBody
() -> () !
AssertionError
<'
static
> |
TreeError
|
OutOfMemoryError
? &
mut
Worker
| &
mut
Allocator
{
let
mut
page =
Html
.
make
()
let
mut
app =
run
program.make<
Search
,
SearchMessage
,
SearchCommand
>()
run
app.
start
(&
mut
page,
0.0
)
run
drain
(&
mut
app, &
mut
page) app.
send
(
SearchMessage
.
ClickedStart
)
run
drain
(&
mut
app, &
mut
page)
run
post
(&
mut
app, &
mut
page,
PORT_PROGRESS
,
"40"
)
run
Testing
.
expect
(
String
.
view
(&app.model.value.progress) ==
"40"
,
"progress arrives"
)
// Cancel, and a post that was already on its way changes nothing.
app.
send
(
SearchMessage
.
ClickedCancel
)
run
drain
(&
mut
app, &
mut
page)
run
post
(&
mut
app, &
mut
page,
PORT_DONE
,
"348513"
)
run
Testing
.
expect
(app.model.value.found.
ownedByteLength
() ==
0
,
"a late answer is dropped"
) }