Derived from: none
Declared in: be/addons/net_server/NetPacket.h
Library: libnetdev.so
As you're writing your fantastic new network add-on, you're liable to need to cope with situations in which timeouts can occur. Maybe an expected packet has taken too long to arrive, or a kernel-level device driver isn't responding fast enough. There are several possible cases in which your add-on will need to be able to time out if something doesn't occur in a reasonable amount of time.
To make handling timeout situations easier, you can use the BTimeoutHandler class. When you create your protocol or network device object, or your packet handler, you can also inherit from BTimeoutHandler to gain access to an easy-to-use timeout mechanism:
class QuickPacketHandler : public BPacketHandler, public BTimeoutHandler { public: virtual bool PacketReceived(BNetPacket *packet, BNetDevice *device); virtual void TimedOut(uint32 receipt); uint32 mainTimeoutReceipt; uint32 otherTimeoutReceipt; }
You can then use the set_timeout() function to register a timeout with the Net Server. For instance, if you want a timeout to occur after 1000 microseconds:
QuickPacketHandler *packetHandler; packetHandler = new QuickPacketHandler(); packetHandler->mainTimeoutReceipt = set_timeout(packetHandler, 1000); packetHandler->otherTimeoutReceipt = 0; /* no timeout set */
The value returned by set_timeout() is the receipt--a unique 32-bit integer that identifies the timeout you've just set. This is passed to TimedOut() when a timeout occurs, and you can pass it to cancel_timeout() to cancel a pending timeout. The receipt is never zero, so you can use a value of zero to represent "timeout not set" if you wish.
If the timeout isn't canceled before 1000 microseconds have passed, the Net Server will automatically call your TimedOut() function. Let's look at a brief example of a TimedOut() function:
void QuickPacketHandler::TimedOut(uint32 receipt) { if (receipt == mainTimeoutReceipt) { /* handle the main timeout */ } else if (receipt = otherTimeoutReceipt) { /* handle the other timeout */ } }
When a timeout occurs and your TimedOut() function is called, the timeout is canceled for you; you don't have to cancel the timeout in this situation. However, if you need to cancel the timeout (if, for example, the packet you're waiting for arrives), you can call cancel_timeout():
cancel_timeout(packetHandler->receipt);
Note that cancel_timeout() returns true if the timeout was canceled and false if the timeout couldn't be canceled. If false is returned, you must wait for the timeout to occur before deleting the BTimeoutHandler. If you delete the object before the timeout occurs, a crash is likely to follow.
virtual void TimedOut(uint32 receipt) = 0
Your derived class must define this function. The Net Server calls it when a timeout occurs.
The receipt parameter tells you which timeout occurred; if you've registered more than one, you can tell which timeout occurred by examining this value.
bool cancel_timeout(uint32 receipt)
Cancels the timeout specified by receipt. This value is returned by the set_timeout() function when you register a BTimeoutHandler with the Net Server.
cancel_timeout() returns true if the timeout was successfully canceled, and false if the timeout could not be canceled. If false is returned, you should wait until the timeout is handled, then call cancel_timeout() again.
uint32 set_timeout(BTimeoutHandler *handler, bigtime_t howlong)
Sets a new timeout, which will occur after howlong microseconds. When the timeout occurs, the specified handler's TimedOut() function will be called.
set_timeout() returns a receipt, which is a unique 32-bit unsigned integer that identifies the newly-created timeout. This value will be passed to TimedOut() when the timeout occurs, and should be passed to cancel_timeout() to cancel the timeout.
The Be Book, in lovely HTML, for BeOS Release 3.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified March 26, 1998.