I/O and network
Networking uses the normal expression syntax and lightweight tasks. The network
names in §4 are reserved, and handles are opaque: they belong to their run and
close when it ends. No CLI flag is needed; --deny-net turns them off
(06b-builtins.md). The functions, the timeouts, the limits
and the errors are in the
TCP, TLS and HTTP page;
the protocol is in docs/vm/10-io-http.md and
docs/vm/10-io-tls.md.
HTTP client and server (std/http) #
HTTP is the std/http library, imported with import HTTP from "std/http"; any
alias works. It calls the internal module HttpWire, which no other module can
name (CHECK-UNKNOWN-NAME). Its builtin records and handles are re-exported
as HTTP.Request, HTTP.Response, HTTP.Header, HTTP.ClientOptions,
HTTP.ServerOptions, HTTP.Client and HTTP.Server (§5b, “Re-exports”) and
reserve no name. A complete program is in
examples/http_server.agc.
Logging (std/logger) #
std/logger is imported with import Logger from "std/logger". It calls the
internal module LogRegistry, which no other module can name
(CHECK-UNKNOWN-NAME). Its builtin types LogRegistry.Level and
LogRegistry.Event are re-exported as Logger.Level and Logger.Event
(§5b, “Re-exports”) and reserve no name. The levels, handlers and formats are
in the
Logger page.
Files and paths #
File, Dir and Path are reserved; File.Handle and File.Info are members
of File. A file handle is opaque, belongs to one evaluation, and closes when
it ends. The host user’s permissions apply; --deny-fs turns these calls off.
Every File, Dir and Path call that takes timeout_ms defaults it to 30000, and
File.open defaults mode to "read" (see “Default parameter values” in
section 6). The calls, the platform differences and the errors are in the
File, Dir and Path page;
the compression calls are in the Zlib
page (Zlib is a reserved
name).
Processes #
Process is an opaque handle, with no constructor, fields, equality or JSON
encoding; IO.inspect prints <Process>. agentica --deny-run file.agc (or
--sandbox) turns the starts off. The calls, the lookup of a command, the
captured output and the channel to a child are in the
Process page.
Native code #
An extern block (section 5) declares C functions of a native library, which a
program then calls like any def. The calls that read and write memory, the
resources, the out parameters, the structs, the compute calls and the waits are
in the
Native code pages.
extern "libm.so.6"
def cos(x: C.Double) -> C.Double
endThe rules (the C types and the codes of a bad one, the library string and
Native.load, Native.function?, resources, callbacks, --deny-native, the
systems that run native code) are in those pages. The language fixes these:
C.UInt64andC.ULongdo not exist (PARSE-EXTERN-TYPE): declare auint64_torsize_tasC.Int64and anunsigned longasC.Long.C.Pointeris a builtin type that any code may hold, with no==. A resource has noto_s(CHECK-TYPE-MISMATCH) and no JSON encoding (CHECK-NOT-ENCODABLE), as other handles.Native.closed?(x)andNative.size_of(Name)take a resource or buffer and a struct name; any other argument isCHECK-TYPE-MISMATCH.Native.callback(Name, &function)takes a declared function named with&: anFnvalue or a function of an extern block isCHECK-NATIVE-CALLBACK.- The VM trusts the signature: a wrong one is undefined behavior in C, and native code runs with the rights of the program.
- A function of an
extern moduleblock (section 5) takes and returnsInt,Float,Bool,String,Bytes,Voidas the result, aList,OptionalorResultof these, aMapwithInt,StringorByteskeys, and the structs and enums of the program that are not generic, whose fields and payloads cross too. A resource of the block crosses as the whole type of a parameter, and anywhere in a result but in a field or payload. Any other type, or two such types or resources of one bare name in one block, isCHECK-NATIVE-TYPEat the type in the signature. - The first call of a module function loads the module and binds the function
by name: the module’s table must have the same canonical signature (aliases
expanded, user types by their bare names), the same mode (
defshort,compute defdirty) and each user type with the same fields or variants, elseRUNTIME-NATIVE-SIGNATURE; a module that does not load isRUNTIME-NATIVE-LOAD. Acompute defof a module runs on the compute pool as one of an extern block does. A resource of a module is a resource as above: owned by the task that made it, held by each call that takes it, and freed once by the module’s free function.