obvious

Tuesday, 26 April 2011
A goal here is to describe C and/or C++ code tactics so they seem obvious, never clever. To folks with 20 years coding experience, this is all old news. You may find yourself asking, "What's so special about that?" Nothing. That's a perfect reaction. Every effect you want to cause in a computing system can be reduced to a simple, explicit manipulation of bytes.

There's no product here. Nothing is being sold. Indifference is a suitable reaction. The aim of these docs is to help anyone who finds code written in thorn style, so dealing with that code is easier. A matter-of-fact description of what, why, and how is the goal. Each piece should seem trivial. Complexity comes from stacking and interaction.

objective

Wednesday, 27 April 2011
You want to know the purpose of code here, right? Perhaps a summary of what is in thorn that isn't in other code systems? Target features providing a raison d'être letting you judge whether you care? Conceptual territory staked out? Hey, what does it matter?

You might as well assume there's no purpose, no target features, no territory. If there is a theme, and I won't admit there is, I see no reason to spell it out. I'd rather sell you on the idea there's nothing at all beyond a random collection of utilities. Works for me.

One jigsaw puzzle I can assemble with these pieces is the async runtime of a peer-to-peer server composed of green threads and lightweight processes, which can manage a lot of connections and data flows with good performance. That's not a product, that's just infrastructure. It would only be special if nothing else did that too. But that's not so.

Most useful to me would be tools making it cheaper to exercise, study, and test other distributed systems I develop as products at work in C, but which are hard to study now outside a narrow context too distant from unit testing. So I hope to extract the makings of an obscenely involved distributed test harness from some of these utilities when assembled. Then I hope to write scripts I can compile to C, and get the same performance of hand-rolled code.

In the meantime, I'm just going to have fun. And I'm not going to tell you where I'm going beyond the above. That would be work. Feel free to cherry pick anything you like.

patterns

Wednesday, 27 April 2011
Several patterns will likely be obvious. I assume you know everything already and merely need briefing on detail. All code looks motivated by NIH (not invented here) given no attempt to re-use code found elsewhere. Api contracts spell out division of responsibilities. Defensive code occurs often, with many asserts and magic signatures used as dynamic type tags. Even C code pursues a casual object-oriented focus. Abstraction is sparse, dominated by concrete code.

Basic data structures get re-rolled from scratch every time a subtle change in focus or emphasis occurs that may affect performance, safety, or scaling in a new context. Hashmaps in particular are likely to be hand-tuned for specific uses. Lists typically use intrinsic linkage, where an object provides space for each list it plans to be put inside. Memory is assumed limited and perhaps statically allocated at startup, so running out of memory is expected and managed.

All C and C++ code lives in some namespace. Namespaces are often two character abbreviations. For example, ns makes a good generic namespace, and might occur in code samples. All C code uses a namespace as prefix with an underscore. So ns_iov is the name of a struct, not iov. You learn to ignore namespace prefixes as meaningless. C code in thorn often uses namespace prefix cy meaning C thorn. So a thorn iovec is named cy_iov. Pick your own namespace.

Stylistically, whitespace is rare because seeing more code at once is helpful. Comments in code are sometimes absurdly dense, focusing on role, consequences, meaning, and redundant summary of purpose detailed elsewhere, to encourage forensic analysis. Variable names in methods can be very short when you can see the entire thing at once. Field names in structs and classes are longer and more unique, assuming global searches are common.

Pointer arithmetic is everywhere, as are function pointers in C code, since vtables and callbacks are considered trivial and used at the drop of a hat. A remedial page on pointer arithmetic might be useful to folks needing a refresher. (This is a good place to start wiki style page names using the camel-case convention: BasicCeePointers is about basic C pointers.) Note wiki is just a pretend wiki; it's just a pile of topics in a semantic network.