The demos are already listed in one plausible order for writing, except a few of them are mutually recursive in the sense they'll use each other, or just refer to one another.
(Descriptions below are written as if the demos are already done, even when they're not started. Check the "completion" section in the right column for a guide to reading rightmost nav bar marks showing which demos are done or partially completed. A dagger — † — means complete; fractions note partial progress.)
The iovec demo comes first, mainly to show context in which þ operates, without using much þ code. One coding style can be used for things outside the library.
However, the fd demo appears first in the menu because it shows a wrapper yfdw for file descriptors used in the iovec demo for primitive system file i/o.
The names page is less a demo and more an introduction to how classes are named in þ. A unified view of naming schemes might help you see holistically.
The assert demo shows simple assert replacements. Using assertions is a global practice, just like logging and tracing is. In fact, I see a log demo must be added too.
The run demo shows yv for basic octet sequences in pointer and length representation. The hex demo shows hexdumping yv, and crc shows use of crc32 for hashing — usually included when dumping yv so comparing by eye for equality is unnecessary.
The buf demo adds a new member var to yv representing max physical capacity, so yb can reserve space for use by yv.
A compare demos shows both simple and complex byte sequence comparisons, for tests and/or app features.
The in and out demos show basic þ i/o apis; and a file demo shows similar apis for files (or things pretending to be files).
The quote demo covers convention to write descriptions of content rather than actual content, with the use of wrapper classes to show intent when writing. A related escape demo describes writing content in a format that can be re-read as literal string values, using escape sequences.
The deck demo shows the start of a trail of general scatter gather representation of octet sequences, with high level uses of refcounting, copy-on-write (cow), and parts of several other demos like slice. Could easily smell like over-engineering.
The cow demo explains some copy-on-write effects and problematic races under threads.
The slice demo shows uniform selection of octet sequence subsets in different formats for i/o purposes.
The rand demo uses pseudo random number generators for typical purposes, using typical routines.
The time demo reads hardware timestamp counters, scales units, and includes brief caveats about system calls.
The stat demo calculates simple standard deviations.
The heap demo shows a little memory alloc abstraction, with direct support for a node demo on refcounts. Subsequent demos show page and book allocation for low-fragmentation, high-granularity, re-usable memory. A short note on the use of primes in hashmap sizes explains how to cut map collisions when keys are patterned values like aligned page and book pointers.
Several later demos touch topics useful under threads, though common practice in making complex systems threadsafe is not addressed — well maybe I'll warn you about avoiding deadlock by choosing canonical lock orders, and avoiding contention by striping locks and mutexes. But it would take an analysis of a real complex system for you to really get the hang of that sort of thing. You'll have to wait until I do a threaded version of an environment for a toy language under mu before that seems like a good idea. That would be less toy-like, and thus a later generation.
The atomic demo shows Intel assembler for atomically incrementing and decrementing integers correctly even under contention by multiple processors, which is used for refcounting and space allocation in pools and ring buffers.
The thread and mutex demos shows C++ wrappers for pthread apis for thread, mutex, and condition variable use. A lock demo shows non-pthread based spin-locking.
The map, list, and iter demos show patterns in api and usage of most þ collection classes.
A ctype demo shows an approach to passing maps of byte or char predicates to routines scanning content.
thorn: todo « Þ, names, fd, iovec, assert, log, run, hex, crc, buf, in, out, quote, escape, compare, file, deck, cow, arc, blob, tree, slice, rand, time, stat, hash, heap, node, primes, page, book, pile, stack, atomic, lock, mutex, thread, map, meter, list, iter, ctype
(mu: toy, peg, imm, tag, box, symbol, token, number, bigint, class, method, reader, writer, eval, env, vm, gc, world, pcode, compiler, asm, lathe, lisp, smalltalk, design, weight, jar, card, harp, debug, profile)
Some demos are stubs: this page is a demo guide. See toy for mu updates on language pages; names introduces naming schemes.
Many demos are yet stubs; this todo page is a guide.
Wil wants to mock up all the demo pages at once, then fill them in as time allows; but this means many pages will remain mostly empty stubs a long time. So this page was added to explain demos before they arrive, as well as track which ones have any content; readers can check here in one place.
For lasting value, this page also explains aspects common to all the demos as a whole. For example, the code shown on these pages are a representative but non-exhaustive sample of classes in þ. Having read all these pages, a developer might easily see how other classes are related, even without dedicated demos here.
Unlike other pages, the right margin nav bar shows progress on page completion for the pages listed. As pages are partially written, annotations for ¼, ½, and ¾ will shows quarters complete. Then complete drafts will be marked with a dagger: †.
Nearly all the demos concern topics and techniques I find trivial. It's partly why I present this material. I don't want to have conversations about old boring stuff any more. Maybe that will happen less if more folks learn to see this kind of thing as trivial too.
One thing about trivial technique is one must choose one or another way to do something, when another way might be chosen instead. I tend to think other choices are obvious; I expect you to choose differently in your clones. The other choices are a little boring too, so don't assume I want to hear about your variations, unless wildly different.
C++ tends to make a few things seem more complex than they are. Some features are for syntax use only. For example, some helper classes appear only to make method dispatch simpler. The value they add might be little more than a single token's worth — but they can occupy one or more lines of complex syntax. Well, so what?
None of the demos show proprietary effects. Nothing is a trade secret. Nothing is patented as far as I know. I haven't filed any, and don't know anyone who has (for material related to demos).
I won't publish any of my interesting tricks related to current employment. (In some cases they're both simple and easy to describe, so only their effects are really of interest.) But don't worry, there aren't any secrets disclosed around here.
A lot of the code is about space management, or related to it. This might also make it look complex. But it's not. At least this amount of space management should look trivial to you if you plan to do systems programming in scaling environments with odd constraints. It's all just thorns. A goal is making right results occur, on purpose.
I expect to wing variations on this stuff in different environments. What I have here often doesn't correspond to any of my earlier projects either. Sometimes code is what I would have done if more complete solutions were allowed. In other cases þ sample code is simpler than real world situations that would need more detail. So add it.
A large part of þ is actually oriented around being able to use large amounts of space in the form of pages and books, for good memory behavior in large scaling systems, and for effective dynamic language runtimes. What might seem like unnecessary complexity is actually a carefully pursued effect: control over granularity, locality, and gc in mixed model systems using both C++ and Lisp.
demos « Þ
† todo « Þ
† names
† fd
† iovec
† assert
† log
† run
† hex
† crc
† buf
† in
† out
† quote
† escape
- compare
- file
- deck
- cow
† arc
- blob
- tree
† slice
† rand
- time
† stat
† hash
† heap
† node
† primes
† page
† book
† pile
† stack
† atomic
- lock
† mutex
† thread
¾ map
½ meter
† list
¾ iter
† ctype