Manpage of TIMEOUT

Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci

---

TIMEOUT

Section: Linux Fast-STREAMS DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

---

NAME

timeout - start a timer

SYNOPSIS

#include <sys/stream.h>
#include <sys/ddi.h>

typedef void timo_fcn_t(caddr_t arg);

toid_t timeout(timo_fcn_t *timo_fcn, caddr_t arg, long ticks);

ARGUMENTS

timo_fcn

the function to call on expiry.

arg

the argument to pass to the callback function.

ticks

the number of ticks to wait before expiry.

INTERFACE

STREAMS.

DESCRIPTION

timeout() starts a timer with duration ticks number of system clock ticks, that, upon expiry, will invoke the supplied timeout function callback timo_fcn (if the timo_fcn function pointer is non-NULL) with the supplied argument arg. The timeout callback function timo_fcn is a function returning void and taking a single caddr_t argument as follows:

typedef void timo_fcn_t(caddr_t arg);

The callback function timo_fcn will be executed at some time greater than or equal to the interval specified in the ticks argument.

RETURN

timeout() returns a toid_t defined as follows:

typedef int toid_t;
typedef int timeout_id_t;

Upon success, timeout() returns a non-zero timeout id and the timeout is scheduled. Upon failure, timeout() returns a zero (0) timeout id and no timeout is scheduled.

ERRORS

When timeout() fails, it returns a zero (0) timeout id. timeout() fails when it cannot allocate the internal structures for the timeout. If it is important that a timeout be scheduled with assurance, the return value should always be checked.

CONTEXT

timeout() can be called from any context including user context, qi_qopen(9), qi_qclose(9), qi_putp(9), and qi_srvp(9) procedures, bufcall(9), qbufcall(9), timeout(9) and qtimeout(9) callbacks, and interrupt service routines.

MP-STREAMS

timeout() is MP-safe.

Considerations should be given when writing the callback function that a timeout() callback function can execute at the same time as any queue qi_qopen(9), qi_qclose(9), qi_putp(9) or qi_srvp(9) procedure, qwriter(9) callout, bufcall(9), qbufcall(9), timeout(9) or qtimeout(9) callback or interrupt service routine. In addition, for a sufficiently small tick values, the callback function may execute before the call to timeout(9) returns.

Nevertheless, the timeout() callback function will be serviced by the same thread as the thread from which the timeout() was issued. Therefore, the callback function will not execute until after timeout() returns, no matter whether ticks is zero or negative. Because the servicing thread and the current thread are the same, the timeout() callback will not be invoked until after the function that called timeout() returns. This means that it is safe to store the returned timeout id in global variables access by the callback function. This is the same situation for qtimeout(9), qbufcall(9), timeout(9), bufcall(9) and esbbcall(9) functions.

However, if the timeout() was generated from a qi_qopen(9), qi_qclose(9), qi_putp(9) or qi_srvp(9) procedure, or was generated from within a mi_bufcall(9), qbufcall(9), qtimeout(9), callback, or other queue referenced bufcall(), esbbcall(9), timeout(9), callback, then the STREAMS executive is aware of the queue to which the callback function is to be referenced and will generate a buffer call internally that is referenced against the queue within whose synchronization context the call was invoked. This makes the timeout() function safer than the normal SVR 4.2 MP equivalent.

See mp-streams(9) for additional information.

NOTICES

For architectural independence, STREAMS drivers and modules should not specify the ticks argument directly, but should use the drv_usectosz(9) and drv_hztousec(9) DKI functions, the Linux HZ define, or some other quantum independent conversion function to convert to and from microseconds or some other absolute unit of time.

toid_t and timeout_id_t should be treated as an opaque type that can be tested for equality to zero. The value should not otherwise be manipulated. Linux Fast-STREAMS implements timeout id values internally as a pointer to a strevent structure containing a Linux timer. On 64-bit architectures, this value should never be stored as an int, nor converted to any integer type with less bits than a pointer.

All outstanding timeout callbacks allocated with timeout() must be cancelled with a call to untimeout(9) before invalidating any of the references passed as an argument to the callback function. When the argument is a queue(9) pointer, all outstanding timeout calls must be cancelled with untimeout(9) before the queue is deallocated (i.e. before returning from the qi_qclose(9)) procedure.

SEE ALSO

untimeout(9), dtimeout(9), itimeout(9), qtimeout(9), quntimeout(9), drv_usectohz(9), drv_hztousec(9).

BUGS

timeout() has no known bugs.

COMPATIBILITY

timeout() is source-level compatible with SVR 4.2 MP DDI/DKI, Solaris® and LiS[1] with the following exceptions:

---

AIX®[2] uses int return value of the timeout() utility. Also, timo_fcn_t is not defined and the prototype for the timeout call out function is void (*func)(void *arg).

---

UnixWare®[3] panics when a timeout structure cannot be allocated, instead of returning zero.

---

Both AIX®[2] and OSF/1®[4] have different prototypes for timeout(9) and untimeout(9) when used for STREAMS as when used for other drivers. The prototypes for timeout(9) and untimeout(9) for use by STREAMS are the old SVR 3[5] definitions which use an int for the toid_t.

---

The Solaris®[6] prototype for this function is as follows:

timeout_id_t timeout(void (*func)(void *), void *arg, clock_t ticks);

Where timeout_id_t is defined as equivalent to toid_t and int, and clock_t is long, this is compatible with other definitions.

---

LiS uses an int as a return value from lis_timeout(). Because of this, the LiS Compatibility Module liscompat(9) lis_timeout() symbol will not function properly on architectures with 64 significant bit pointers and 32-bit ints.

---

timeout() allocates a strevent structure that includes an embedded Linux kernel timer. timeout() assigns a packed out-dating pointer into the integer toid_t returned. This pointer is a sequenced pointer to a strevent object that expires when the timeout sequence number is incremented. This permits unpacking and dereferencing of the pointer instead of searches for id numbers in strevent lists for speed.

LiS provides a wrapper to Linux Kernel timer functions to implement timeout(). LiS's implementation creates a Linux timer structure, assigns it a sequential integer timer identifier, and places it in a timer list. Whenever LiS starts a timer it checks the list to see if the integer timer identifier is unique. This is an exhaustive linear search. This is inefficient. STREAMS drivers or modules that set timers often will experience poorer performance than if the Linux kernel timer facility was used directly.

---

Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility considerations.

CONFORMANCE

SVR 4.2 MP DDI/DKI[7], Solaris® documentation.

HISTORY

timeout() first appeared in SVR 2[8].

REFERENCES

[1]

LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>

[2]

AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>

[3]

UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>

[4]

Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>

[5]

SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

[6]

Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>

[7]

USL DDI/DKI, Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual for Intel Processors, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

[8]

SVR 2, UNIX® System V Release 2 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

TRADEMARKS

OpenSS7tm

is a trademark of OpenSS7 Corporation.

Linux®

is a registered trademark of Linus Torvalds.

UNIX®

is a registered trademark of The Open Group.

Solaris®

is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

Linux Fast-STREAMS: Package streams version 0.9.2.4 released 2008-10-31.

Copyright©1997-2008OpenSS7 Corp. All Rights Reserved.
(See roff source for permission notice.)

---

Index

NAME

SYNOPSIS

ARGUMENTS

INTERFACE

DESCRIPTION

RETURN

ERRORS

CONTEXT

MP-STREAMS

NOTICES

SEE ALSO

BUGS

COMPATIBILITY

CONFORMANCE

HISTORY

REFERENCES

TRADEMARKS

IDENTIFICATION

---

This document was created by man2html, using the manual pages.
Time: 23:46:57 GMT, May 24, 2013