ACTIVE_JOB structure

The ACTIVE_JOB structure is defined in eventset.h as follows:

typedef struct active_job {
	struct active_job *next;
	struct active_job **prevnextp;
	tSMEventId event;

		/* in C++ these would be virtual functions */
		// handle a channel with an active event, must return
		// non-zero if the channel has been deleted from the
		// list of active channels
	int (*handler)(struct active_job *acp);

		// run when the channel is deleted from the list of
		// active channels. It could delete the channel or
		// put it into a pool of channels awaiting re-use.
	void (*cleanup_fn)(struct active_job *acp);

		/* application-specific fields
		 * in C++ these would be in a class derived from
		 * this one
		 */
	struct appactive *mf;
} ACTIVE_JOB;

Now, there is something very unusual about this structure, to which you must pay close attention. The final element, mf, is declared as being of type struct appactive *, however struct appactive is not defined here - or indeed anywhere else! (So don't go looking for it). Instead, you have to define this yourself, in your own source code. It can be any kind of structure you like.

To create an ACTIVE_JOB structure, you must first define struct appactive, then you must create an instance of struct appactive, and initialize it. Only now are you in a position to initialize an ACTIVE_JOB by filling in the mf field with a pointer to the struct appactive you've just set up.

The reason for this is that the value of mf will be passed back to the callback functions handler and cleanup_fn, and this mechanism provides a typesafe way of achieving that aim.

• When the event is triggered, the handler() callback will be called.
• When the ACTIVE_JOB is about to be deleted, the cleanup_fn() callback will be called.

Fields

You are responsible for filling in the following fields before passing this structure to any of the EVENTSET functions:

• event
• handler
• cleanup_fn
• mf

You should leave the following fields well alone:

• next
• prevnextp

See also

EVENTSET