tibrvcmEvent_Destroy()

Function

Declaration

tibrv_status tibrvcmEvent_Destroy(
    tibrvcmEvent          cmListener,
    tibrv_bool            cancelAgreements);
tibrv_status tibrvcmEvent_DestroyEx(
    tibrvcmEvent          cmListener,
    tibrv_bool            cancelAgreements,
    tibrvEventOnComplete  completionFunction);

Purpose

Destroy a certified delivery listener.

Parameter	Description
`cmListener`	Destroy this listener.
`cancelAgreements`	`TIBRVCM_CANCEL` cancels all certified delivery agreements of this listener; certified senders delete from their ledgers all messages sent to this listener. `TIBRVCM_PERSIST` leaves all certified delivery agreements in effect, so certified senders continue to store messages.
`completionFunction`	Rendezvous software runs this function immediately after all instances of the event’s callback function have completed. If the event’s callback function is not running when the event is destroyed, the destroy call runs it before returning. If this parameter is `NULL`, `tibrvcmEvent_DestroyEx()` does not run a completion function; instead, its behavior is the same as tibrvcmEvent_Destroy(). See tibrvEventOnComplete.

Remarks

Destroying event interest invalidates the event object; passing the event object as an argument to subsequent API calls produces an error.

Canceling Agreements

When destroying a listener, a program can either cancel its certified delivery agreements with senders, or let those agreements persist (so a successor listener can receive the messages covered by those agreements).

When canceling agreements, each (previously) certified sender transport receives a REGISTRATION.CLOSED advisory. Successor listeners cannot receive old messages.

Extended Function

Although tibrvcmEvent_Destroy() and tibrvcmEvent_DestroyEx() prevent future dispatch calls from running the destroyed event’s callback function, that callback function might be already running in one or more threads that dispatch events from the same queue. In each thread where the callback function is already in progress, that callback function does continue to run until complete.