Multiple resource serialization for REXX programs. Source code included.
Program is distributed as ZIP package: download to temporary directory and unpack to destination folder. See below for download link(s).
Following ones are the download links for manual installation:
Cereal (29/6/2002, Chris Angelico) | Readme/What's new |
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. |
www.kepl.com.au/esstu/programs/cereal.zip | local copy | |
Cereal (29/6/2002, Chris Angelico) | ||
hobbes.nmsu.edu/download/pub/os2/dev/tools/misc/Cereal_1-0-0.zip |
This work is licensed under a Creative Commons Attribution 4.0 International License.
Comments
Martin Iturbide
Tue, 08/08/2023 - 22:59
Permalink
New LInk: https://hobbes.nmsu
Add new comment