StrawLibCopyright ©2005 Pär Spjuth
The StrawLib API
The API for the StrawLib is based on macros. For those who see macros as something evil this solution must be defended by the fact that the macros basically serves the purpose of hiding several global variables. They also do some token pasting to automate most of the execution logging.
The framework has been divided into six categories for easier navigation:
Starts a new straw se
#define STRAW_STARTSESSION(Session_p, AllocMem, FreeMem, ClassName)
#define STRAW_PROCESSEVENT(Session_p, EventHight, EventLow, EventData_p, EventConsumed_p)
#define STRAW_DEFINECLASS(ClassName, EntryChunk, PrivateDataType)
#define STRAW_DEFINECLASSNODATA(ClassName, EntryChunk)
This macro begins a event map, i.e. the first step to make the straw wait for one or more evens before continue executing. Below is an example of how the following macros are used to build a complete event map:
CHUNK_BEGINMAP CHUNK_MAPEVENT(0, SIG_OP_SUCCESS, MatchHTTPOp, HandleResult) CHUNK_MAPEVENT(0, SIG_OP_FAILURE, MatchHTTPOp, CleanUp) CHUNK_ENDMAPANDWAIT
Fist we use CHUNK_BEGINMAP to mark the beginning of the map. Then we start mapping events to chunks using CHUNK_MAPEVENT. Each event has a corresponding matching function that will be used to verify that the event was really aimed at this straw. At last we exit the chunk and waits for the events using CHUNK_ENDMAPANDWAIT.
This macro defines a event mapping and can hence only be used between the CHUNK_BEGINMAP and CHUNK_ENDMAPANDWAIT macros. What could seem a little tricky about this mapping is that you have to assign a event matching function. This function will be used, if the mapping gets a hit on a event, to make sure the event was aimed at the specific straw, e.g. if there are several instances of the same straw class all of them might be waiting for the same event.
Because there are situations when you might want to map a event no matter what, two predefined event mappers are defined:
The CHUNK_MATCHALL matcher will match all events of the given type, and the CHUNK_MATCHDROPPED will have the same function except it will not match if there is another straw that also match the event. This is useful if a straw should only handle events dropped by all other straws, e.g. to be able to send back an error event.
int ExampleEventMatcher(STRAW_ID StrawID, void* StrawData_p, void* EventData_p);
#define CHUNK_MAPEVENT(EventHigh, EventLow, Matcher, Chunk)
This is a convenient macro if you are only going to map a single event. It is basically just a short for building a event map using the macros listed above.
#define CHUNK_MAPANDWAIT(EventHigh, EventLow, Matcher, Chunk)
Gets the upper 32-bits of the event type.
Gets the lower 32-bits of the event type.
Checks if the event types matches the event triggering the chunk.
#define CHUNK_ISEVENT(EventTypeHigh, EventTypeLow)
Gets the data of the event that triggered the current chunk.
Removes the current cleanup chunk for the straw (if any). This means that the straw will be removed instantly when it is terminated.
Instantly leaves the current chunk and start executing the chunk given as parameter. This is basically a simple goto - no extra heap will be used to run the next chunk, and no other straw will be run while jumping. This also means that child straws that are started in the current straw will not be run until the current straw waits for an event.
See also CHUNK_YIELD
Moves the execution to the given chunk, but first lets the integration environment and other straws a chance to execute. This macro should be used instead of CHUNK_JUMP in places where synchronous processing is likely to lock up the execution for some time.
See also CHUNK_JUMP
This macro makes a another straw terminate and waits on it to finish terminating. It is not possible to terminate the current straw using this macro. If the specified straw does not exist the notification chunk will be executed immediately.
#define CHUNK_TERMINATESTRAW(Straw, NotifyChunk)
Gets the ID of the current straw. This value can always be converted to any type that can be converted to a pointer.
#define CHUNK_INIT(ChunkName, VariableName, DataType)
#define CHUNK_RUNSUBSTRAW(ClassName, PrivateData_p, ReturnChunk)
#define CHUNK_STARTCHILDSTRAW(ClassName, PrivateData_p)