# The Network Kit: BTimeoutHandler

Derived from: none

Declared in: be/addons/net_server/NetPacket.h

Library: libnetdev.so

## Overview

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.

## Member Functions

### TimedOut()

          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.

## Global C Functions

### cancel_timeout()

          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.

### set_timeout()

          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.