The Event Loop

All commands in libraw1394 are asynchronous, with some synchronous wrapper functions for some types of transactions. This means that there are two streams of data, one going into raw1394 and one coming out. With this design you can send out multiple transactions without having to wait for the response before you can continue (sending out other transactions, for example). The responses and other events (like bus resets and received isochronous packets) are queued, and you can get them with raw1394_loop_iterate().

This forms an event loop you may already know from similar systems like GUI toolkits. raw1394_loop_iterate() gets one message from the event queue in raw1394, processes it with the configured callback functions and returns the value returned by the callback (so you can signal to the main loop from your callback; the standard callbacks all return 0). It normally blocks when there are no events and always processes only one event. If you are only receiving broadcast events like isochronous packets you thus have to set up a loop continuously calling the iterate function to get your callbacks called.

Often it is necessary to have multiple event loops and combine them, e.g. if your application uses a GUI toolkit which also has its own event loop. In that case you can use raw1394_get_fd() to get the file descriptor used for this handle by libraw1394. The fd can be used to for select() or poll() calls (testing for read availability) together with the other loop's fd, some event loops also allow to add other fds to their own set (GTK's event loop does). If these trigger on the libraw1394 fd, you can call raw1394_loop_iterate() once and it is guaranteed that it will not block since at the very least one event waits. After the first call you continue the main event loop. If more events wait, the select()/poll() will immediately return again.

You can also use the fd to set the O_NONBLOCK flag with fcntl(). After that, the iterate function will not block anymore but fail with errno set to EAGAIN if no events wait. These are the only legal uses for the fd returned by raw1394_get_fd().

There are some functions which provide a synchronous wrapper for transactions, note that these will call raw1394_loop_iterate() continuously until their transaction is completed, thus having implicit callback invocations during their execution. The standard transaction functions have names of the form raw1394_start_xxx, the synchronous wrappers are called raw1394_xxx.