Macintosh Development

[Home] [About Us] [People] [Information Systems]
[Kerberos for Macintosh] [Applications] [Miscellaneous Documentation]

Idle Library API Functions

Boolean IdleGetThreaded (void);
void IdleSetThreaded (Boolean isThreaded);

IdleGetThreaded() and IdleSetThreaded() get and set whether the Idle Library is running in multithreaded mode or not. In singlethreaded mode, the library periodically calls WaitNextEvent() when it is blocked on the network to give time to other applications. It also calls the list of event handlers with the events it receives so that the application can respond to cancel events and window updates.

In multithreaded mode, the Idle Library periodically calls YieldToAnyThread() whenever a sockets API function is blocked on the network. When running in multithreaded mode, an application should never call functions which use the Idle Library that block from it's main thread.

Boolean IdleGetShouldIdle (void);
void IdleSetShouldIdle (Boolean shouldIdle);

IdleGetShouldIdle() and IdleSetShouldIdle() get and set whether the Idle Library does anything. By default, idling is on. However, if you need to use a library which calls the Idle Library at interrupt time, you can turn off idling with these functions.

IdleEventHandlerUPP NewIdleEventHandlerProc (IdleEventHandlerProcPtr);

Creates an event handler UPP from a procedure pointer. The IdleEventHandlerProcPtr is of the form:

Boolean IdleEventHandlerProcPtr(EventRecord *theEvent, UInt32 refCon);

OSStatus IdleAddEventHandler (IdleEventHandlerUPP eventHandlerUPP, Boolean isApplication, UInt16 mask, UInt32 refCon);
OSStatus IdleRemoveEventHandler (IdleEventHandlerUPP eventHandlerUPP);

Only used in singlethreaded mode.

Adds and removes an event handler from the list of event handlers. All event handlers receive null events. For non-null events, the event handlers are called in the order they were installed until one returns true (it handled the event). You should never return true unless you handle the event completely. You should never return true when passed a null event.

isApplication tells the Idle Library whether or not you are the application. If you are a library or plugin, pass false. If you are the application, pass true and make sure you can handle suspend/resume events. Only pass true if you are prepared to handle suspend/resume events (ie: handle private scrap, etc). Note that if there is no application event handler, only null events will be returned to any of the handlers and suspend/resume will be disabled.

mask is the event mask for the events your handler wants to receive and refCon is a pointer for data which will be passed into your event handler (to avoid globals).

You can use the event handler to respond to events that come in while waiting on the network. By default, there is no event handler, although command-. support is enabled.

void IdleSetActive (IdleEventHandlerUPP eventHandlerUPP);
void IdleSetInactive (IdleEventHandlerUPP eventHandlerUPP);

IdleSetActive() and IdleSetInactive() change whether or not an event handler in the event handler list is currently active. An inactive event handler will not be called. These functions are reentrant, so you can safely nest calls to them.

You can use these functions to wrap routines which call into a library which uses the Idle Library. For instance if the Kerberos 4 library calls the Sockets Library (which uses the Idle Library), then the Kerberos 4 will wrap all its exported functions so that they turn on the Kerberos 4 Library's event handler for the duration of the exported function.

UInt32 IdleGetEventSleepTime (void);
void IdleSetEventSleepTime (UInt32 eventSleepTime);

Only used in singlethreaded mode.

Gets and sets the time (in ticks -- 1/60 of a second) WaitNextEvent() will sleep waiting for an event. This value can be changed to optimize performance of network operations. By default this is 1.

UInt32 IdleGetIdleFrequency (void);
void IdleSetIdleFrequency (UIn32 idleFrequency);

Gets and sets the period (in ticks -- 1/60 of a second) between calls to WaitNextEvent() or calls to YieldToAnyThread(). This value can be changed to optimize performance of network operations.

Boolean IdleHandleEvent (EventRecord *theEvent);

IdleHandleEvent() takes and event and calls each of the installed event handlers, allowing each one to try to handle the event until an event handler returns true. If a handler handled the event, IdleHandleEvent() returns true, otherwise it returns false.

OSStatus Idle ();

If you have called IdleSetThreaded() and set Idle Library in threaded mode, Idle() calls YieldToAnyThread() to give time to the other threads.

If the library is in non-threaded mode, it gives time to the event handlers. If the application has installed an event handler, it calls WaitNextEvent() and passes those events to the handlers using IdleHandleEvent(). Otherwise it passes only null events to the handlers. Idle() always checks for command-. and escape and returns userCanceledErr if either was pressed. Callers of Idle() should always handle userCanceledErr appropriately.

Questions or comments? Send mail to macdev@mit.edu
Last updated on $Date: 2003/11/19 20:49:31 $
Last modified by $Author: smcguire $