The PhotoJazz engine is a reentrant shared library. If your product can handle multiple threads, or if it runs in a multithreaded environment, you will need PhotoJazz to yield time to other threads. At the least, you will probably want the user to able to cancel the process. PhotoJazz itself never deals directly with the thread manager. Instead, it frequently calls a yield function that you define. PhotoJazz uses an object-oriented C structure, JzYielder, for this purpose, which contains a callback function for yielding, as well as a private data field reserved for your use. The callback function takes the JzYielder object as its first argument.

typedef struct JzYielder {

int (*mYield)(struct JzYielder *aYielder);
unsigned long mData;

} JzYielder;

You must create an instance of this structure, define an mYield function, set the function pointer in the structure instance to your function, and pass a pointer to the structure instance in to PhotoJazz each time you start to read or write a PhotoJazz file with JzReadBegin or JzWriteBegin. PhotoJazz stores this address and yields to other threads by calling through the function pointer in the structure pointed to by that address.

mYield

The mYield function, which you define, takes as its argument a pointer to a JzYielder structure (aYielder), and yields time to other threads as necessary, in particular checking whether the user wants to cancel the process. When PhotoJazz calls this function, it passes back the address of the JzYielder structure you gave it at the beginning of the file with JzReadBegin or JzWriteBegin. If the user wants to cancel the read or write process, your mYield function must return TRUE (1). Otherwise, your mYield function must return FALSE (0). To permit PhotoJazz to clean up its state properly, you must return control to PhotoJazz, which will then return an error result (kJzStreamResultCancelled) indicating user cancellation through the JzRead or JzWrite function in progress.

int (*mYield)(JzYielder *aYielder);

For example, a basic Macintosh implementation of mYield might be:

int MyYield(JzYielder *aYielder){

int lQuit = 0;
static long sOldTime = 0;
long lTime;
lTime = TickCount()>>3; //Convert ticks to eighth-seconds (roughly).
if (sOldTime!=lTime){

sOldTime = lTime;
EventRecord lEvent;
if (WaitNextEvent(everyEvent, &lEvent, 1, NULL)){

lQuit = DoEvent(&lEvent);

}

}
return lQuit;

}

mData

The mData member of the JzYielder structure is solely for your use; PhotoJazz never accesses it. Depending on your thread package's needs, you can ignore it, put an identifying number in it, or put in a pointer to a structure containing additional information. PhotoJazz accesses the JzYielder structure by reference only and defines no hidden members of its own in the structure, so you are free to define your own structure with a JzYielder as its first member instead of forcing your ancillary data to fit in the mData field.

unsigned long mData;

Examples

A sample code snippet using the MyYield function defined above might be:

JzYielder lYielder;
lYielder.mYield = MyYield;

Depending on your needs, you may prefer to create a global, static, or dynamic JzYielder instead of a local one.