Tasks and tests
Task is reserved. Tasks are cooperative and run on the VM’s schedulers, so
tasks may run in parallel (--schedulers N, section 6b). Every Task function,
its timing, cancellation and crash behaviour, and its runtime errors are in the
Task page. The rules of the
language and the checker:
- A
Task[R]has no constructor, equality, fields, indexing or JSON encoding.Task.spawn(&f) do ... endisCHECK-BLOCK-TARGET. - A handle (a file, a socket, a listener, a process or a
std/httpserver) belongs to the task that opened it, and it is closed when that task ends, in any way.Task.spawn_owning(&f, handle)is the one way to hand a handle over; an argument that holds no handle isCHECK-NOT-A-HANDLE. AnAddressis data, not a handle: a channel passed as its address in that argument is shared, not handed over. - A runtime error in a task other than
mainis a crash that ends only that task.Task.awaitof a crashed or cancelled task returns an error of kindtask.crashedortask.cancelledwhen the result type is aResult, and halts withRUNTIME-TASK-CRASHEDorRUNTIME-TASK-CANCELLEDotherwise. Await[T](Await.Done(value)andAwait.TimedOut, written without parentheses),TaskRef,TaskDownandTaskExitare reserved: a struct, enum, type parameter or import alias with one of these names isCHECK-REDEFINED-NAME.Awaitis matched withcaseand checked for exhaustiveness like a user enum, andtrydoes not apply to it. For aTask[Void]the payload is matched asAwait.Done(_); a named binding there isCHECK-VOID-TYPE.Task.map(items, limit, timeout_ms) do |item| ... endis always writtenTask.map(...), not as a method, soxs.mapstays the sequentialList.map. The block gives aResult[R], andtryworks in it.- Argument types of
Task.cancelandTask.monitor, and the reserved opaqueTaskRefofTask.current, are in theTaskpage. - A BDD step handler must finish its tasks before it returns
(
RUNTIME-BDD-PENDING-TASKS). Seebdd.md.
Channels #
Channel is reserved. A Channel[T] is a bounded queue that tasks send values
into and receive values from, and a handle: assigning or passing it shares the
same channel. The functions, the timeouts, the order of waiters, the ownership
of a channel and the checker rules (the type T, the expected type of
Channel.new, what puts, == and JSON do with a channel) are in the
Channel page.
channel.address gives an Address[T]: a send-only reference to the channel
that is data, so a table, a map, a list, a struct, an enum payload or a
message can hold it, and == compares which channel it names. It has send
only, so the channel’s owner stays its one reader, and it does not keep the
channel alive. It cannot be JSON-encoded (CHECK-NOT-ENCODABLE), be a map key
or set element (CHECK-MAP-KEY-TYPE, CHECK-SET-ELEMENT-TYPE) or be in a
constant (CHECK-CONSTANT-TYPE). Its sends and errors are on the Channel
page. Address is not reserved: a program may declare a struct, enum or
alias named Address with no type parameters, but one with type parameters is
CHECK-REDEFINED-NAME, since Address[T] always names the builtin.
Shared tables (ATS) #
ATS (Agentica Table Storage) is reserved. An ATS[K, V] is a mutable table
that tasks share through a handle, the role of Erlang’s ETS: values stay
immutable, and a table is the one place where shared data changes in place. The
functions, atomicity, costs, lifetime and the checker rules (where a table may
be held, the types K and V, the expected type of ATS.new, the effects of
its functions) are in the
ATS page.
Unit tests (Test) #
Test is reserved; Test.Case is its member. Test is a builtin module that
needs no import. A test file is a program whose main calls Test.run with a
list of Test.test(name) do ... end blocks, and the block returns
Result[Void]. The assertions, the report, Test.run and the order in which a
test fails are in the Test page.
- Test functions: a
*_test.agcfile may have nomain. Thenagentica testruns its top-leveltest_*functions, in source order, as ifmaincalledTest.runwithTest.test("name", &test_name)for each; the name is the function name withouttest_, with each_a space. A file with bothmainandtest_*functions isCHECK-TEST-MAIN, atmain, whatever thetest_*functions are. Withoutmain, a test function takes no parameters and its result is writtenResult[Void], not an alias of it (CHECK-TEST-SIGNATURE, at the function), andtest_alone isCHECK-TEST-NAME.agentica checkapplies these rules to a*_test.agcfile; a run of such a file with nomainis stillCHECK-MAIN, and in a file of any other nametest_*functions are ordinary functions.
agentica test #
agentica test [PATH...] [--steps FILE] [--only TEXT] [--tags EXPR] [--jobs N] [--timing] [--coverage] [--isolate] runs .feature specifications
and *_test.agc unit test files in one report, and its exit code is the
verdict.
BDD is the standard module std/bdd, written in Agentica, and BDD is not
reserved. A BDD. call
without import BDD from "std/bdd" is CHECK-UNKNOWN-NAME, with the import as
its help. The discovery
rules, timeouts, output limits, seeds, runner protocol and step catalog are in
bdd.md.
Not planned: an assertion that stops the test by itself (Agentica has no
exceptions; try is the one way to stop early); running tests in the runner’s
own VM; a child VM per test (a task per test is enough); and describe, setup
and tags (a helper function does what setup does).