ChPulsar

send a message periodically


Constructor

#include "Ch/ChPulsar.h"

ChPulsar( const bigtime_t interval,
          BMessage *msg = NULL,
          const char *name = "ChPulsar",
          BHandler *handler = NULL,
          int32 priority = B_URGENT_PRIORITY );

Create a new ChPulsar named name that will send a message, msg, to the specified handler every interval microseconds. The pulsar thread will run at the specified priority.

If no message is specified, B_PULSE messages will be delivered; if the specified handler has a Pulse() method, it will be activated as usual.

The msg is owned ChPulsar; it'll destroy the message itself, you should not destroy it.

Note: Because the default priority is pretty high, it's a very good idea to lower this if you're going to be sending ChPulsar messages with a short interval. If you don't, your application won't have time to respond to the messages; it'll be flooded, the UI won't be responsive, the system will get sluggish, you'll suffer from male pattern baldness, and the user will get annoyed and delete your app.

The Pulse() method of BView and friends isn't reliable; according to the documentation, it's called only when no other messages are pending. ChPulsar on the other hand will send its message as long as the handler's message queue isn't full.

If the handler's message queue is full when a ChPulsar message is supposed to be delivered, it will be ignored, the the pulsar will wait until its next message time to try again.

Message contents

In addition to the existing message contents (either a plain B_PULSE or whatever you specified), the ChPulsar will add the following:

Name Type Description
pulsar_bigtime int64 (Actually, it's a bigtime_t.) The system time when the message was sent, in microseconds, since the beginning of the UNIX epoch (January 1, 1970). See real_time_clock_usecs() in the Kernel Kit for details.
pulsar_fire double The temperature of the motherboard when the message was sent. See is_computer_on_fire() in the Kernel Kit for details.
pulsar_interval int64 (Actually, it's a bigtime_t.) The interval when the message was sent; this will be the interval passed to the constructor unless you've changed it with SetInterval().
pulsar_on int32 Whether the computer was on when the message was sent. See is_computer_on() in the Kernel Kit for details.
pulsar_sequence uint64 A sequence number; you can use this to see if the number of messages sent from the pulsar matches the number you've received, to see how many messages the pulsar's sent, to calculate the number of messages sent per second, etc.
pulsar_time int32 The system time when the message was sent, in seconds, since the beginning of the UNIX epoch (January 1, 1970). See real_time_clock() in the Kernel Kit for details.

Methods

IsValid()

bool IsValid( void );

Is the ChPulsar valid? Returns true if it is, or false if it isn't.

A ChPulsar could be invalid if you specified an invalid handler in the constructor, if we couldn't create a valid ChSnoozer, or we couldn't spawn the pulsar thread.

It's a good idea to check IsValid() before calling Start().

Start()

status_t Start( void );

Start the ChPulsar's pulsar thread. After the number of microseconds specified in the interval, your handler will receive the specified msg.

Due to timing jitter and scheduling latencies, the message will almost never be sent after exactly interval microseconds. This is a fact of life, even in realtime operating systems.

Start() returns B_NO_ERROR for success, or:

B_BAD_THREAD_ID
The pulsar thread is invalid.
B_BAD_THREAD_STATE
The pulsar thread is already running.

Suspend()

status_t Suspend( void );

Stop sending ChPulsar messages without causing the pulsar thread to exit. You can start sending messages again by calling Start().

Suspend() returns B_NO_ERROR for success, or B_BAD_THREAD_ID if the pulsar thread is invalid.

Status()

status_t Status( thread_state *state );

Get the state of the pulsar thread. The various thread states are documented in get_thread_info in the Kernel Kit.

Status() returns B_NO_ERROR for success, or B_BAD_THREAD_ID if the pulsar thread is invalid.

GetInterval()

bigtime_t GetInterval( void );

Return the current message interval, in microseconds.

SetInterval()

void SetInterval( bigtime_t new_interval );

Set the message interval to new_interval. Note that the message interval won't be updated until after the current interval has expired (i.e., if the pulsar thread is currently waiting to send a message, it won't know it should wait for a different amount of time until it wakes up and sends the message).

To set the message interval immediately, you could do this:

    status_t retval = pulsar->Suspend();
    if( retval == B_NO_ERROR ) {
        pulsar->SetInterval( new_interval );
        retval = Start();
    }

This stops the pulsar thread, updates the interval, and restarts the thread, which will now wait using the new interval.


Please see the libCh Overview for licensing information.


Last modified: $Date: 1998/04/13 11:39:35 $