Cereal

Cereal - simple multiple resource serialization for REXX programs The Problem: A VX-REXX program needs to manage a pool of 50 fundamentally identical resources. Several different threads may need them simultaneously, and one thread may require more than one at a time. Each routine needs to request a resource and be told which one (1-50) it has been allocated, and then needs to relinquish control when it is finished. The Cereal-less Solution: Use a Muxwait semaphore, Or mode, to control 50 mutex semaphores. This results in good, but not perfect, results. A thread cannot block on a muxwait when it owns one of the muxwait's semaphores; also "The Dreaded One-Oh-Five Plague" - if a thread dies while owning a semaphore, the next thread to request the muxwait gets error 105 and no sem. The Cereal Solution: Let Cereal manage your semaphores. Just call CerealRequest to ask for a resource; and when you're finished, call CerealRelease with the resource ID. The Cereal functions are thread-safe, and process-separate. Technical information: Cereal doesn't actually use the OS/2 semaphore services, except for one "master" sem - governing access to a section of memory. Each resource is represented by one byte, with value 0x00 for unowned, and nonzero (currently always 0x01, may later be owner tid or similar) for owned. This block of data is returned by CerealStatus, and is reset by CerealClear. Function Descriptions ~~~~~~~~~~~~~~~~~~~~~ CerealLoadFuncs - load all the Cereal functions Usage: call RxFuncAdd "CerealLoadFuncs","Cereal","CerealLoadFuncs"; version=CerealLoadFuncs(dllname) Parameters: DLL name (optional). If omitted functions are loaded from Cereal.DLL. Returns: Version string for Cereal. The first word (blank-delimited) is the three-part version number (Major.minor.revision); everything else should be treated as a single human-readable string with author/contact details. CerealRequest - request one resource Usage: which=CerealRequest(howmany) Parameter: Number of resources Returns: Number from 1 to howmany indicating which resource has been claimed, or "" if no semaphore available. CerealRelease - release one resource Usage: call CerealRelease which Parameter: Resource ID as returned by CerealRequest Returns: 0 for success, OS/2 error code for failure (usually 288 for semaphore not owned). CerealStatus - request status information Usage: info=CerealStatus(howmany) Parameter: Number of resources to return status for (should match the howmany used with CerealRequest for best results) Returns: String of characters (length = howmany), each of which represents one semaphore, and is 0x00 for unowned, or some other value for owned. CerealClear - erase all status information Usage: call CerealClear howmany Parameter: Number of resources to force-release Returns: Always "". Caution: This function will cause all semaphores to be cleared, even if owned. DO NOT USE THIS CARELESSLY! Use at your own risk, the author is not responsible, etc, etc, etc.