assembly VS hitchstory

When you're learning something for the first time, it can be hard to know what mental model you need to have to be effective with the tool.

Some documentation is reference material. With reference material you might navigate the reference material in a particular traversal to get what you need to do what you want.

But at the beginning of your journey, you need to be taught a "flow" an expected pattern of operation to build up the right mental model of how an average session with the tool works. For programming this might be the edit file, compile, run, debug loop, or TDD or IntelliJ's build and deploy. Or a CI system commit, push, deploy, promote cycle. Or kubernetes kubectl edit, apply.

I opened the "dining philosophers TLA+" example and ran it - this seemed to be an affordance of the TLA+ Toolbox GUI which was straightforward to understand.

But then I tried to use the tool with my own. I interpreted the existing code of the dining philosophers and tried to make my own ringbuffer model.

It took me a while that I needed to update this screen to put in the following details that I have filled in on the screenshot:

https://github.com/samsquire/assembly/blob/main/screenshots/...

You have to put your entrypoint in the "temporal formula" and then put your model arguments on the right hand side.

I was able to piece together the operation of this tool by piecing together various reference details together, it wasn't until I saw that screenshot I referenced in my OP that I realised I needed to do that step to get the PlusCal code to update the TLC code that follows it. I was wondering why it didn't work until I saw that screenshot.

Thank you for this in-depth article.

I am a less than a C++ beginner but I asked Stack Overflow how to run C++ coroutines in a thread pool. It seems coroutines in C++20 are unfinalised but don't quote me on that but I did get some sourcecode for older versions of the C++20 standard.

I used Marce's Col's excellent blog post about how to create coroutines in assembly by adjusting the RSP pointer.

https://blog.dziban.net/posts/coroutines/

I extended Marce's code to run the coroutines in kernel threads:

https://github.com/samsquire/assembly (see threadedcoroutines.S)

I have been thinking of coroutines in terms of query compilation for database engines and the volcano query model and this article:

https://www.chiark.greenend.org.uk/~sgtatham/coroutines.html

Tying together two pieces of code that call eachother in push or pull driven style is really powerful. Or if you're running multiple independent tasks that need their own state. This as I understand it is the original intent of object orientation that Alan Kay wanted and is represented by Erlang and partly Go.

Specifically, I am thinking of compiler created coroutines where code can be interleaved at compile time rather than at runtime.

Thank you for your ideas and thoughts.

This might be relevant - I've been playing around with some assembly to unwind the stack, but it occurred to me I don't need to pop the stack to scan through it. So like C++ exception handling (I learned about it in the Itanium C++ ABI) or algebraic effects, you can scan memory if you have access to the stack start in memory (I do that by storing the rsp somewhere in .global main) in theory it's just data.

I need to generate sections of lookup data for range information for associating .text code section addresses with function names.

In theory this would also be useful for coroutines since a coroutine position/state is just a program counter position of code that you can JMP to in your yield function (that isn't a call but an offset)

To move a coroutine from one thread to another or another machine over the network or persist to disk, let me think. We could do what C++ coroutines does and have a promise struct object that is presumably on the stack when a coroutine resumes by jumping to that coroutines location.

I think the hard part is being stackless and persisting the current coroutine state. You could mov $COMPILER_DETERMINED_OFFSET into -10(%rbp) that promise object and then when the coroutine resumes it does a JMP -10(%rbp) in a label before the coroutine body.

I am a beginner to assembly programming but here is my program: https://github.com/samsquire/assembly/blob/main/stackunwind....

https://github.com/samsquire/assembly/blob/main/coroutines.S

This might be useful to someone who wants to port this to C. This uses the stack switching idea. So they are stackful coroutines.

There's also Tina a header only coroutine library

I built something like this too:

https://github.com/hitchdev/hitchstory/blob/master/examples%...

I took the same approach to "docs are tests and tests are docs" with integration testing when I created this library: https://github.com/hitchdev/hitchstory

I realized at some point that a test and a how-to guide can and should actually be the same thing - not just for doctests, but for every kind of test.

It's not only 2x quicker to combine writing a test with writing docs, the test part and the docs part reinforce each other:

* Tests are more easily understandable when you attach written context intended for human consumption.

* Docs are better if they come attached to a guarantee that they're valid, not out of date and not missing crucial details.

* TDD is better if how-to docs are created as a side effect.

I have created a project for easily writing this type of test with YAML:

https://github.com/hitchdev/hitchstory

I dont think that this type of task is really appropriate for an LLM though. It is better to use hard abstractions for the truly deterministic stuff and for other stuff where you may need to do subtle trade offs (e.g. choosing a selector for the search bar) an LLM will generally do a bad job.

For those interested in the concept of having permanently up-to-date documentation with screenshots I built this testing framework based upon the idea that good documentation can be a autogenerated artefact of good tests:

https://github.com/hitchdev/hitchstory

I don't like gherkin. It's it has very awkward syntax, it's not type safe, it's very verbose, it has no ability to abstract scenarios and rather than being a source for generating the documentation it tries to be the documentation.

Nonetheless, there is a small number of projects where they either work around this or it doesn't matter as much. I find that most people that apply gherkin to their projects find it doesn't work - usually for one of the above reasons.

I built https://github.com/hitchdev/hitchstory as an alternative that has straightforward syntax (YAML), very strict type safety (StrictYAML), low verbosity, and is explicitly designed as a source for generating documentation rather than trying to be the documentation.

I built this because I had the same idea: https://github.com/hitchdev/hitchstory

If the specification can be tested and used to generate docs and can be rewritten based upon program output then the maintenance cost for producing docs like these plunges.

-c fsync=off -c synchronous_commit=off -c full_page_writes=off

I got the answer from Karen Jex at Djangocon 2023.

I used it to build some integration tests which exhibit best practices: https://github.com/hitchdev/hitchstory/tree/master/examples/...

I considered using tmpfs but I wanted to cache the entire database volume and couldnt figure out how to do that with podman.

This is incredible work.

To anyone curious, I highly recommend:

- https://hitchdev.com/hitchstory/approach/

- https://hitchdev.com/hitchstory/why-not/

From the overall RDD/BDD type home page:

- https://hitchdev.com/hitchstory/

The entire product site is a thing of richly informative beauty.

---

My only question was whether the generated 'docs' snippets would add value over just reading the story in your DASL. Any markdown site generator (such as the chosen Material for MKDocs) can just embed the ```yaml anyway. But then I realized what was generating e.g. …

- https://hitchdev.com/hitchstory/using/engine/rewrite-story/

… and how superior that is to typical docs, especially typical docstring or swagger factories.