Writing Handler Functions¶
The handler function is the key component of a continuation. It is supposed to examine the event and event data, and then do something appropriate. The probable action might be to schedule another event for the continuation to received, to open up a connection to a server, or simply to destroy itself.
The continuation’s handler function is a function of type
TSEventFunc. Its arguments are a continuation, an event, and a
pointer to some data (this data is passed to the continuation by the
caller - do not confuse this data with the continuation’s own data,
TSContDataSet()). When the continuation is called back,
the continuation and an event are passed to the handler function. The
continuation is a handle to the same continuation that is invoked. The
handler function typically has a switch statement to handle the events
static int some_handler (TScont contp, TSEvent event, void *edata)
You might notice that a continuation cannot determine if more events are
“in flight” toward it. Do not use
TSContDestroy() to delete a
continuation before you make sure that all incoming events, such as
those sent because of
TSHttpTxnHookAdd(), have been handled.
TS_HTTP_SEND_REQUEST_HDR_HOOK may callback several times when the OS crashed. Be careful to use functions such as TSContDestroy in TS_HTTP_SEND_REQUEST_HDR_HOOK hook.
The following table lists events and the corresponding type of void* data passed to handler functions:
The continuation functions are listed below:
When a handler function blocks, it blocks the event thread running it. This blocks all the continuations (internal ones along with those of plugins) in the event thread’s queue. This may increase the worst-case latency for HTTP request processing. If there is enough blocking, this could increase CPU idle time, which may reduce proxy throughput. The Au test polite_hook_wait illustrates a method for using dynamic threading to do a blocking call without blocking any handler function. But the overhead of this method may cancel out the performance improvement, if blocking times are short.