Galaxy Communicator Documentation:

MITRE Utilities: Polling Stdin


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, but is not available on Win32.

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.


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.


Please send comments and suggestions to: bugs-darpacomm@linus.mitre.org
Last updated September 20, 2001

Copyright (c) 1998 - 2001
The MITRE Corporation
ALL RIGHTS RESERVED