
<<FILE:  CoFork.mesa     Last Editor: Sturgis    July 23, 1981  3:32 PM>>


CoFork: DEFINITIONS =

BEGIN

CoForkMe: PROCEDURE RETURNS[--put-- POINTER];

END.


<<template for use of CoForkMe>>

<<first a few arbitrary type names, and constants>>

RequestType: TYPE = CARDINAL; -- any type desired
ItemType: TYPE = CARDINAL; -- any type desired
InitialParamsType: TYPE = CARDINAL; -- (can be several individual parameters, does not have to be a single parameter)

NullItem: ItemType; -- item to be returned to consumer after producer has terminated
NullRequest: RequestType; -- request to be fed to producer after consumer requests termination.

<<types and code associated with the producer>>

ItemSource: TYPE = POINTER TO PORT[RequestType] RETURNS[ItemType];
ItemSink: TYPE = POINTER TO PORT[ItemType] RETURNS[RequestType];
ItemStopper: TYPE = PROCEDURE[RequestType];

Producer: PROCEDURE[
assortedInitialParams: InitialParamsType, -- arbitrary number
initialRequest: RequestType, -- not always needed, see example below
putItem: ItemSink] =
BEGIN
request: RequestType;
item: ItemType;

<<>>
<<>>

request _ putItem[item]; -- can be called at any point, and from any depth of procedure call, as many times as desired

<<>>
<<>>

END;

MakeProducer: PROCEDURE[initial: InitialParamsType]
RETURNS[getItem: ItemSource, stopItems: ItemStopper] =
BEGIN
putItem: ItemSink _ CoForkMe[];
Producer[initial, putItem[NullItem], putItem];
END;


<<code associated with the consumer>>

BEGIN
initial: InitialParamsType;
getItem: ItemSource;
stopItems: ItemStopper;
item: ItemType;
request: RequestType;

<<>>
<<>>

[getItem, stopItems] _ MakeProducer[initial];

<<>>
<<>>

item _ getItem[request]; -- this call may occur as often as desired and nested to any procedure call depth.

<<>>
<<>>

stopItems[NullRequest]; -- it is important that this call contain NullRequest, and it is essential that getItem and stopItems not 
be called after this call.
<<>>
<<>>

END;


<<notes:>>

1) The sequence of events is as follows:
a) The Consumer calls MakeProducer.
b) MakeProducer calls CoForkMe.  CoForkMe returns to MakeProducer retaining its own frame in existence.
c) MakeProducer coCalls putItem with nullItem as argument.  This coCall is "captured" by CoForkMe, which preserves the argument 
(nullItem) for later use, and then fakes a return by MakeProducer to the Consumer.
d) The Consumer coCalls getItem with the first request.  This coCall results in a coReturn to MakeProducer, delivering the first 
request to MakeProducer. 
e) MakeProducer calls the Producer, supplying the initial arguments, the first request, as well as putItem. 
f) The Producer coCalls putItem, delivering an item.  This coCall results in a coReturn to the consumer with the item.
g) The Consumer coCalls getItem with a request, which results in a coReturn to the producer with the request.
h) f and g alternate until either the Producer returns to MakeProducer, or the Consumer calls stopItems.
i) If the Producer returns to MakeProducer before the Consumer calls stopItems, then MakeProducer immediately returns.  This return 
is "captured" by CoForkMe.  CoFork me now repeatedly delivers nullItem (saved from step c) to the consumer until the consumer calls 
stopItems.
j) If the Consumer calls stopItems before the Producer returns to MakeProducer, then CoForkMe repeatedly returns the request value 
delivered by the Consumer in StopItems to the Producer.  This continues until the Producer returns to MakeProducer. 

2) The structure of MakeProducer:
a) Any desired arguments.
b) Return parameters exactly [ItemSource, ItemStopper].
c) MakeProducer Code has following steps:
i) call CoForkMe, saving putItems.
ii) call putItems with NullItem as argument, saving the returned firstRequest.
iii) Either examine the returned firstRequest and decide whether to call the Producer, or always call the Producer with the 
firstRequest.
iv) RETURN

3) The structure of the Producer:
a) any desired arguments, including putItems, and possibly including firstRequest.
b) assorted coCalls on putItem, watching for nullRequest as a response suggesting that the producer return.
c) The producer may return at any time, and may continue to produce items even after receiving nullRequest.
d) no return parameters. (This is not checked, DISASTER would result.)

4) The structure of the Consumer:
a) A call on MakeProducer, saving getItem and stopItems.
b) Assorted calls on getItem, always watching for nullItem, which suggests that the producer has terminated.
c) The Consumer may continue to call getItem after receiving nullItem.
d) A call on stopItems, with nullRequest as the argument.
e) No more calls on getItem after calling stopItems.  (This is not checked, DISASTER would result.)

5) The types ItemSource and ItemSink must be complementary.  ItemStopper must have no result and take a RequestType as the one 
argument.  (This is not checked, DISASTER would result.)

END.


<<MODULE HISTORY>>

<<Initial by: Sturgis, July 23, 1981  2:01 PM>>


(2048)
tedly 