NAME

       TSContCall - TSContCall API function

SYNOPSIS

          #include <ts/ts.h>

       int TSContCall(TSCont contp, TSEvent event, void *edata)

DESCRIPTION

       Call  the  continuation  contp  as  if from a hook with the event type event and data of edata. Presuming
       contp was created in a manner like:

          TSContCreate(CallbackHandler, TSMutexCreate());

       Therefore there is a function:

          int CallbackHandler(TSCont this, TSEvent id, void * data);

       As a result TSContCall() will effectively do:

          return CallbackHandler(contp, event, edata);

       If there is a mutex associated with contp, TSContCall() assumes that mutex is held already.  TSContCall()
       will directly call the handler associated with the continuation.  It will return the  value  returned  by
       the handler in contp.

       If  contp  has  a  mutex,  the  plugin  must  acquire  the  lock  on  the  mutex for contp before calling
       TSContCall(). See TSContMutexGet() and TSMutexLockTry() for mechanisms for doing this.

       The most common case is the code called by TSContCall() must complete before further code is executed  at
       the  call  site. An alternative approach to handling the locking directly would be to split the call site
       into two continuations, one  of  which  is  signalled  (possibly  via  TSContCall())  from  the  original
       TSContCall() target.

       Note  mutexes returned by TSMutexCreate() are recursive mutexes, therefore if the lock is already held on
       the thread of execution acquiring the lock again is very fast. Mutexes are also  shareable  so  that  the
       same mutex can be used for multiple continuations.:

          TSMutex mutex = TSMutexCreate();
          TSCont cont1 = TSContCreate(Handler1, mutex);
          TSCont cont2 = TSContCreate(Handler2, mutex);

       In  this  example  case, cont1 can assume the lock for cont2 is held. This should be considered carefully
       because for the same reason any thread protection between the continuations is removed. This  works  well
       for tightly coupled continuations that always operate in a fixed sequence.

COPYRIGHT

       2024, dev@trafficserver.apache.org

9.2                                               Apr 01, 2024                                   TSCONTCALL(3ts)