Document spans, interop, csv, parallel, and combine
- Language basics: add Span/RoSpan section with construction, operations and lifetime rules - Writing programs: add full Spans in .NET interop subsubsection (arrays-as-spans, #:copy for span returns, span values and their restrictions); update performance notes to remove "without spans" - Standard library: split std/units+rational into two subsections with fuller descriptions; add std/parallel+combine, std/interop, and text/csv+csv-codec subsections - index: mention CSV in the text module description 🤖 Generated with [ECA](https://eca.dev) (anthropic/claude-sonnet-4-6) Co-Authored-By: eca-agent <git@eca.dev>
This commit is contained in:
parent
d16bf477a1
commit
6ee8ca62b9
4 changed files with 109 additions and 7 deletions
|
|
@ -1669,6 +1669,77 @@ A generic .NET type is imported with type variables, and a generic method names
|
|||
|
||||
Bjolang types and .NET types line up: @code{(-> %a %b)} is a @code{Func<A, B>}, @code{(Seq %a)} an @code{IEnumerable<T>}, @code{(Array %a)} a @code{T[]}, and a C# tuple is a @code{Tuple}. Two things do not work yet: building a generic .NET class from a type only known at runtime, and constructor patterns on .NET objects.
|
||||
|
||||
@subsubsection{Spans}
|
||||
|
||||
Many .NET methods take a @code{Span<T>} or a @code{ReadOnlySpan<T>} instead of an array. You can work with them in two ways: pass an @code{(Array %a)} directly, or use the prelude's @code{(Span %a)} and @code{(RoSpan %a)} types.
|
||||
|
||||
@strong{Arrays where .NET takes a span.} A @code{ReadOnlySpan<T>} or @code{Span<T>} parameter accepts an @code{(Array %a)}, both in an @code{import/extern} signature and in a @code{(.Method obj ...)} call. The span views the array in place, so a method that writes into a @code{Span<T>} mutates the array. When a method is overloaded, an overload taking @code{T[]} wins over a span overload, and @code{ReadOnlySpan<T>} wins over @code{Span<T>}:
|
||||
|
||||
@codeblock[#:lang "bjolang"]|{
|
||||
(import/extern
|
||||
(ascii? (: System.Text.Ascii.IsValid (-> (Array byte) bool))) ;; ReadOnlySpan<byte>
|
||||
(write-be! (: System.Buffers.Binary.BinaryPrimitives.WriteInt32BigEndian (-> (Array byte) int void))) ;; Span<byte>
|
||||
(reverse! (: System.MemoryExtensions.Reverse (-> (Array %a) void)))) ;; Span<T>
|
||||
}|
|
||||
|
||||
A span that a .NET member @em{returns} is not an array. To copy a returned span into a fresh @code{(Array %a)}, mark the @code{import/extern} clause with @code{#:copy}:
|
||||
|
||||
@codeblock[#:lang "bjolang"]|{
|
||||
(import/class
|
||||
(Encoding (: System.Text.Encoding)))
|
||||
|
||||
(import/extern
|
||||
(utf8 (: System.Text.Encoding.UTF8 #:get))
|
||||
(preamble (: System.Text.Encoding.Preamble (-> Encoding (Array byte)) #:get #:copy))
|
||||
(drop-span (: System.MemoryExtensions.AsSpan (-> (Array %a) int (Array %a)) #:copy)))
|
||||
|
||||
(preamble utf8) ;; utf8.Preamble.ToArray()
|
||||
}|
|
||||
|
||||
@code{#:copy} emits @code{.ToArray()} on the call itself, so no span is kept in a local variable and the imported binding can even be passed as a first-class function value. Without @code{#:copy}, declaring a span return as an array is a compile error. @code{#:copy} cannot be combined with @code{#:async}, @code{#:set}, or @code{(out T)} parameters.
|
||||
|
||||
@strong{Spans as values.} To slice an array or pass views around without allocating, use @code{(Span %a)} (.NET's @code{Span<T>}) and @code{(RoSpan %a)} (@code{ReadOnlySpan<T>}), which are in the prelude:
|
||||
|
||||
@codeblock[#:lang "bjolang"]|{
|
||||
(: sum (-> (Span long) long))
|
||||
(defun (sum s)
|
||||
(let loop ((i 0) (acc 0L))
|
||||
(if (< i (span-length s))
|
||||
(loop (+ i 1) (+ acc (span-ref s i)))
|
||||
acc)))
|
||||
|
||||
(def xs #[1L 2L 3L 4L])
|
||||
(sum (array->span xs #:from 1 #:to 3)) ;; 5, and nothing is copied
|
||||
(span-set! (array->span xs) 0 10L) ;; xs[0] = 10
|
||||
}|
|
||||
|
||||
@read-table{
|
||||
| @code{Span} | @code{RoSpan} | Does |
|
||||
|--------------------------------------+-----------------------------------------+-----------------------------------------------------|
|
||||
| @code{(array->span a #:from #:to)} | @code{(array->ro-span a #:from #:to)} | a view of @code{a} from @code{#:from} to @code{#:to}|
|
||||
| @code{(span-length s)} | @code{(ro-span-length s)} | number of elements |
|
||||
| @code{(span-ref s i)} | @code{(ro-span-ref s i)} | element at @code{i} |
|
||||
| @code{(span-set! s i x)} | | writes @code{x} into the underlying storage |
|
||||
| @code{(span-slice s #:from #:to)} | @code{(ro-span-slice s #:from #:to)} | a sub-view of @code{s}; nothing is copied |
|
||||
| @code{(span->array s)} | @code{(ro-span->array s)} | a fresh array copy of the span's elements |
|
||||
| @code{(span->ro-span s)} | | the same view, read-only |
|
||||
}
|
||||
|
||||
@code{#:from} defaults to @code{0} and @code{#:to} defaults to the length. Neither span type converts to the other implicitly; use @code{span->ro-span} when a @code{RoSpan} is needed. In @code{(std mutable vec)}, @code{(mutablevec-span v start n)} returns a @code{(Span %a)} over @code{n} elements of a @code{MutableVec}'s backing storage (valid until the vector's length changes), which pairs with @code{(mutablevec-grow! v n)} to fill a vector a block at a time.
|
||||
|
||||
You can also call a span's .NET members directly: @code{(.-Length s)}, @code{(.Slice s 1)}, @code{(.Fill s x)}, @code{(.get_Item s i)} for @code{s[i]}, and @code{(.set_Item s i x)} for @code{s[i] = x} (an indexer returning @code{ref T} reads a copy of the element, and @code{.set_Item} writes through the reference).
|
||||
|
||||
@strong{Where a span may not go.} A span—or any other .NET @code{ref struct}—is a view of memory that is valid only while the call that made it runs. It can be a local variable, a parameter, or a return value of a function called by name, and the compiler refuses it everywhere it could outlive the call:
|
||||
|
||||
@read-list{
|
||||
- Inside another value: a vec, list, tuple, record, union, @code{Option}, or @code{Result}.
|
||||
- As a type argument of a generic function or trait (such as @code{(println s)} or @code{loop}'s @code{:for} over a collection); walk a span by index instead.
|
||||
- As a parameter or result of a function @em{value} (a @code{(fun ...)} or a function passed as a value is a .NET delegate, which cannot take or return a span). Write a local @code{(defun ...)} and call it by name.
|
||||
- Captured from an outer scope by a @code{(fun ...)}, a local @code{(defun ...)}, a non-tail-recursive @code{let} loop, a @code{(seq ...)}, or a hoisted form. Pass the span to the local function as an argument instead.
|
||||
- In scope across a suspension point in a bjoroutine, or across a @code{(yield ...)} in a @code{(seq ...)}. Do the span work in a synchronous @code{(defun ...)} helper so the span ends before the fiber suspends or yields.
|
||||
- As a parameter or return value of a bjoroutine, an argument to @code{(bjo ...)}, or a module-level @code{def}.
|
||||
}
|
||||
|
||||
@subsubsection{Culture and formatting}
|
||||
|
||||
A Bjolang program runs in the invariant culture, so a double formats with a decimal point (@code{2.5}) and not as @code{2,5} on a machine where it otherwise would. Set @code{CultureInfo.CurrentCulture} if you want local formatting.
|
||||
|
|
@ -2528,7 +2599,7 @@ A percentage can be written @code{2} or @code{2%}. A benchmark file is an ordina
|
|||
@code{prepare} runs a benchmark's setup and warms it up and calibrates it, as a run would. @code{sample} takes one sample of @code{k} calls, and @code{:ns} is the whole sample's time. Anything wrong is answered with @code{(error "why")}, and the session goes on. A served program prints nothing else, so its output is the protocol and nothing more. A script that compares two builds made by two different compilers, which is not something @code{bjo bench} does by itself, can drive both of them this way, or use @code{--against PATH --against-build "CMD"}.
|
||||
|
||||
@subsection{Performance}
|
||||
Bjolang is compiled into pretty straight-forward c#, but without spans or ref structs. It performs pretty similar to c#, except for some small corners of the language that are different.
|
||||
Bjolang is compiled into pretty straight-forward c#. It performs pretty similar to c#, except for some small corners of the language that are different.
|
||||
|
||||
@subsubsection{Strings}
|
||||
Strings in bjolang are utf8, as such they do @em{not} support random access. This means we navigate them differently, using string-cursors, which is explained in the part about strings. Navigating a string using cursors is slower than blasting through integer indices, and if your code needs to be really fast, there are some things you can think about:
|
||||
|
|
@ -2545,7 +2616,7 @@ When parsing strings with a known format, (std scan) will be a lot faster than (
|
|||
@subsubsection{loops}
|
||||
Most of the time you should use the @code{loop} form. It will be the fastest, and is usually flexible enough to do what you need. The only case is for hot loops (ones that are run often) that are performance sensitive. For those, using the various @code{-fold}, @code{-for-each}, and @code{-iter} functions will be faster for the collections that are tree-based. Those collections are: @code{Vec}, @code{Map}, @code{HashSet}, @code{OrderedMap}, and @code{OrderedMap}. The overhead of loop vs. fold is often something like 3x, with fold being as fast or slightly faster thana @code{foreach} on a C# @code{List<T>}. It does not, however, beat using indexed iteration over the @code{List<T>} due to the @code{foreach} doing some safety checks to detect concurrent mutation.
|
||||
|
||||
The absolutely fastest collection to loop over is, unsurprisingly, the Array. In bjolang it should be just as fast as in c# (again, without spans).
|
||||
The absolutely fastest collection to loop over is, unsurprisingly, the Array (or a @code{Span} over part of one). In bjolang it should be just as fast as in c#.
|
||||
|
||||
The loop form gets turned into a kind of goto soup. For the single level case, it is just as efficient as a c# @code{while} loop, but for really complex cases with many levels and subloops with clauses the JIT in dotnet may struggle. In that case you either live with the clarity and simplicity it gives, or you reach for the glorified gotos of names lets. This is probably not going to be a problem though. I tried to rewrite the worst loop form in bjolang (a 16 line monstrosity with one large multi-level claused subloop and a regular subloop) and there was no difference.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue