Galaxy Communicator Documentation:

MITRE Utilities: Polling Stdin

License / Documentation home / Help and feedback

Sometimes, the user might find it convenient to poll stdin periodically, as a way of getting input from the user or as a way of allowing the user to control when certain events occur (such as when an audio device starts to listen). We provide a way of doing a non-blocking poll on stdin, and controlling the behavior when a line is read. This functionality is available with the MIT timed task loop or without. On Unix, this utility uses the timed task loop by default; on Windows, it uses Windows threads.

We have provided a complex example of this functionality in our toy travel end-to-end "system".

See the page on compiling and accessing these utilities.


Creating and activating a poll

We distinguish between creating a poll object and activating it. Although servers which poll stdin should only accept a single connection at a time, the poll object should be stored in a connection rather than a server, because of the type of its argument.

 typedef Gal_Frame (*MGal_StdinFrameCreator)(char *str)

MGal_StdinPoll *MGalIO_CreateStdinPoll(char *prompt, GalIO_CommStruct *comm, MGal_StdinFrameCreator fn, int ms, int activate)
The prompt is the string which will be printed out to stdout every time the poll is activated. The comm is a connection to the Hub. The fn is a function which is called whenever a line of text is read, which creates a frame which will be sent to the Hub as a new message. The ms are the number of milliseconds for the Galaxy timed task; 0 is the default (100 ms), -1 means don't set up a timed task, and anything else is taken as a number of milliseconds. The activate argument should be 1 if the poll should be activated immediately, 0 if the poll will be activated later.

The fn may choose not to return a frame, in which case polling continues.

MGal_StdinPoll *MGalSS_EnvCreateStdinPoll(char *prompt, GalSS_Environment *env, MGal_StdinFrameCreator fn, int ms, int activate)
The environment-aware version of MGalIO_CreateStdinPoll. See the documentation on session management.

void MGal_ActivateStdinPoll(MGal_StdinPoll *poll_struct)
This function activates the poll, which means that the prompt is printed out and a timed task is created, if the polling milliseconds are not -1. If you're in a dispatch function and you return the poll structure from _GalSS_init_server, you can access the poll structure using GalIO_GetServerData:

Gal_Frame reinitialize(Gal_Frame f, void *server_data)
{
  /* set up poll for stdin */
  MGal_ActivateStdinPoll((MGal_StdinPoll *) GalIO_GetServerData(server_data));
  return f;
}
Typically, you'll reactivate the poll every time you want to start listening again. It is possible to call MGal_ActivateStdinPoll within the frame creation function to restart the poll immediately, whether or not the frame creation function returns a frame.

void MGal_SetStdinPollData(MGal_StdinPoll *poll_struct, void *data)
This function sets the data for the poll object to some arbitrary element for later retrieval.

void *MGal_GetStdinPollData(MGal_StdinPoll *poll_struct)
This function retrieves the arbitrarily stored data.

void MGal_SetStdinPollPrompt(MGal_StdinPoll *poll_struct, char *prompt)
Resets the poll's prompt. This does not take effect util MGal_ActivateStdinPoll is called the next time.

void MGal_FreeStdinPoll(MGal_StdinPoll *poll_struct)
Use this function to free a poll structure. This should always be called when terminating. On Windows, it's especially important, because it notifies the thread which reads from stdin to shut down.


Doing without the timed task loop

As with other polling functions, it is possible to use this functionality without the normal MIT server structure. Two problems must be addressed. First, we need a function which creates a stdin poll not for a GalIO_ServerStruct, but for a GalIO_CommStruct. Second, we need a polling function to use ourselves.

int MGal_PollStdin(MGal_StdinPoll *poll_struct)
This is the polling function to use with the polling structure. It returns 1 if it read a line successfully, 0 if it hasn't encountered a line yet.


License / Documentation home / Help and feedback
Last updated August 8, 2002