[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 1

tstop Kernel Service

Purpose

Cancels a pending timer request.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/timer.h>
int tstop (t)
struct trb *t;

Parameter

t Specifies the pending timer request to cancel.

Description

The tstop kernel service cancels a pending timer request. The tstop kernel service must be called before a timer request block can be freed with the tfree kernel service.

In a multiprocessor environment, the timer function associated with a timer request block may be active on another processor when the tstop kernel service is called. In this case, the timer request cannot be canceled. A multiprocessor-safe driver must therefore check the return code and take appropriate action if the cancel request failed.

In a uniprocessor environment, the call always succeeds. This is untrue in a multiprocessor environment, where the call will fail if the timer is being handled by another processor. Therefore, the function now has a return value, which is set to 0 if successful, or -1 otherwise. Funnelled device drivers do not need to check the return value since they run in a logical uniprocessor environment. Multiprocessor-safe and multiprocessor-efficient device drivers need to check the return value in a loop. In addition, if a driver uses locking, it must release and reacquire its lock within this loop, as shown below:

while (tstop(&trb))
  release_then_reacquire_dd_lock;    
                 /* null statement if locks not used */

Execution Environment

The tstop kernel service can be called from either the process or interrupt environment.

Return Values

0 Indicates that the request was successfully canceled.
-1 Indicates that the request could not be canceled.

Implementation Specifics

The tstop kernel service is part of Base Operating System (BOS) Runtime.

Related Information

The talloc kernel service, tfree kernel service, tstart kernel service.

Timer and Time-of-Day Kernel Services, Using Fine Granularity Timer Services and Structures, Using Multiprocessor-Safe Timer Services in AIX Kernel Extensions and Device Support Programming Concepts.


[ Previous | Next | Contents | Home | Search ]