README.md (3372B)
1 # The npthread library - notes 2 3 The included copy of npthread.html was last modified Sat 21 Jun 2003 00:03:18 UTC (Epoch +1056153798) 4 5 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. 6 7 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. 8 9 <a id="state"></a> 10 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> 11 12 User-defined lights (npthread_watchflag and npthread_waveflag) could be used internally to implement the message and trylock notes. 13 14 This package requires tai support, which can be had from many different places. 15 16 ## Rules of programming with npthreads 17 18 See the above paragraph about [state saving](#state). 19 20 **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. 21 22 **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. 23 24 **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.