commit f7f9a3903afa0c007d579f667422d85ffda42f8d
parent 91954e159ec6549ee9d8fed662bb87a6b93ae99c
Author: Ellenor Bjornsdottir <ellenor@umbrellix.net>
Date: Mon, 7 Nov 2022 08:41:16 +0000
what is even this I am losing my entire-
Diffstat:
5 files changed, 65 insertions(+), 1 deletion(-)
diff --git a/doc/npthread/README.md b/doc/npthread/README.md
@@ -1,13 +1,24 @@
# The npthread library - notes
-This copy of npthread.html was last modified Sat 21 Jun 2003 00:03:18 UTC (Epoch +1056153798)
+The included copy of npthread.html was last modified Sat 21 Jun 2003 00:03:18 UTC (Epoch +1056153798)
This npthread aims to be capable of exact conformance with the Bernstein documented npthreads by default. If you define NPTHREAD_VPTR, this compliance is lost, but the 'n' your f(n) is called with is expected to be a void pointer instead of an int64. I believe this use to be much more likely to be useful for most users.
If you include sc_npthread.h as well as npthread.h, you would gain access to additional thread call conditions to be determined. In thread-safe sc_npthread, those call conditions may involve pthread trylock successes, or data (from another true thread) in a mailbox area.
+<a id="state"></a>
Your threads should have a mechanism for saving their state, so if they choose to cut mid-procedure (e.g. starving of data from a fildes or the rendezvous area, or of a locked resource, or buffered I/O needs to drain before continuing), they can resume processing. In 2000, Simon Tatham designed a header capable of helping you do this. It is available under the MIT licence. <https://www.chiark.greenend.org.uk/~sgtatham/coroutines.html>
User-defined lights (npthread_watchflag and npthread_waveflag) could be used internally to implement the message and trylock notes.
This package requires tai support, which can be had from many different places.
+
+## Rules of programming with npthreads
+
+See the above paragraph about [state saving](#state).
+
+**Suitcase Extension:** There is an array called VTLS - for virtual-thread local storage. This array is as it says - it is storage local to your virtual thread. It's a dynamically-allocated, null-hashed table of void pointers. It can be read and modified directly if you'd like, but additions and subtractions must be effected by a macro (or function?) that ensures that there are enough places on the array, and loads a magazine of unused places to fire instead of allocating a new place. Use liberally. It will be nuked (run-through at O(n) in a single physical thread, and any item that is not NULL will be freed) when your thread exits.
+
+**Suitcase Extension:** If you need to keep it across jumps or coroutine rejoins, use your VTLS! This includes pointers to connection or channel state for an IRC server, for instance. VTLS is implemented the same way errno is in modern UNIXes - that is, the "vtls" global is actually a function call that returns a pointer to the thread's vtls (the "errno" global is actually a dereference of the return of a similar function call). Thread ownership of the VTLS is only ensured by programmer discipline - technically, a thread can pass a portion of its VTLS to another thread, by way of the mailbox extension.
+
+**Suitcase Extension:** In thread-safe npthreads built with thread-safe iolib, physical thread ownership of your virtual thread's data structures is ensured by readers/writer locks. The physical thread holds a writer lock on your virtual thread's data structures (VTLS, as well as the right to modify iolib file descriptors related to your virtual thread by a wantread or wantwrite) for as long as it is executing your virtual thread. **Do NOT pass data structures out of your thread by reference** without using more granular locking at your own level. Doing so breaks the guarantees provided by a readers/writer lock.
diff --git a/doc/nullhash/README.md b/doc/nullhash/README.md
@@ -0,0 +1,9 @@
+# Nullhash
+
+This is my own idea, but it's based on other things. It's either a simple array, or a synthesis of two dynamically-allocated structures - a simple array, and a ring buffer. The array's objects are pointers to voids. The dynamic ring buffer is a "magazine" of ssize_ts representing deallocated positions. It's not intended that you use the synthesis to build a hash table upon, as in the hash table example, you don't have as much control of the key as in, say, a thread table, or something where the application doesn't even need to see your keys.
+
+If you need to iterate over the items in a nullhash, your structure should be a linked list also containing your key. A means of creating a linked list will be supplied.
+
+UTHash does all the things - it hashes, it creates a table, and it does the linked list thing. Nullhash does none of that by itself - you have to do that.
+
+(Am I Sisyphus?)
diff --git a/doc/typealloc/3typealloc/typealloc.3 b/doc/typealloc/3typealloc/typealloc.3
@@ -19,5 +19,33 @@ In source (auto-generate libraries for manipulating your TypeAllocs):
.Fn TypeAlloc_append ta type field len a base ta_rplus ta_append
.Fn TypeAlloc_copy ta type field len a base ta_ready ta_copy
.Fn TypeAlloc_free ta type field len a base ta_free
+.Sh "Field names and their types"
+A "ta_rplus" field refers to the \fBname\fR of a function comparable to stralloc_readyplus(sa, length);.
+
+A "ta_ready" field refers to the \fBname\fR of a function comparable to stralloc_ready(sa, length);.
+
+A "ta_append" field refers to the \fBname\fR of a function comparable to stralloc_cat(sa, items, length);.
+
+A "ta_free" field refers to the \fBname\fR of a function comparable to stralloc_free(sa);.
+
+Other fields:
+.Bl -tag -width "-w size "
+.It ta
+is the name of a typealloc.
+.It type
+is the name of the type that that typealloc stores an array of.
+.It field
+is the name of the field of the typealloc that points to the beginning of the array. This can safely be 's' if you'd like.
+.It len
+is the name of the field that describes the number of items in the array.
+.It a
+is the name of the field that describes the number of items that can be in the array before it has to be expanded.
+.It base
+Unclear, but I've only ever seen it at 10. It is an operand of the use of __builtin_mul_overflow in the typeallocdefs header.
+.El
.Sh Description
TODO: describe all these \fBmacros\fR.
+.Sh History
+A GEN_ALLOC facility first appeared in qmail. The typealloc facility, derived from the GEN_ALLOC facility, originated in Nightmare Mail (2022).
+.Sh Copyright
+Inconsistent with the rest of suitcase, the changes to GEN_ALLOC that make it typealloc are licenced to you under the terms of the Creative Commons Zero licence. To the extent that I, Ellenor et al Bjornsdottir, hold copyright in this work, I grant you full licence to use the parts of this work I hold copyright in as if it had lapsed into the public domain. Where that is not possible, permission to use, copy, modify and redistribute the parts of this work I hold copyright in is granted, free of further hindrance, and also without any warranties express or implied, including that of merchantability, fitness for purpose, or noninfringement of others' copyrights (though I do not believe any are infringed).
diff --git a/head/io/io.h b/head/io/io.h
@@ -85,6 +85,7 @@ extern void io_wait();
extern void io_check();
#endif
+// returns an index (identical to an fd number for which this is true)
extern int64 io_canread();
extern int64 io_canwrite();
diff --git a/head/nullhash/nullhash.h b/head/nullhash/nullhash.h
@@ -0,0 +1,15 @@
+#ifndef SC_NULLHASH_NULLHASH_H
+#define SC_NULLHASH_NULLHASH_H
+
+/* Like all hash tables, Nullhash is built on a concept of buckets.
+ * The buckets contain a pointer to a list of the objects they represent.
+ * Unlike most hash tables, it does not supply the hash function, hence
+ * the name Nullhash.
+ * It's intended for tables where keys are small integers, such as file
+ * descriptors in Suitcase iolib or in a program, or (with the addition
+ * of a recycling tray) where it is not important to the application
+ * what the key is, so long as there is one that can be passed around,
+ * used for a handle into data structures, and then got rid of.
+ */
+
+#endif // SC_NULLHASH_NULLHASH_H
