vrpn_BaseClass.h

Go to the documentation of this file.

 
#ifndef VRPN_BASECLASS
#define VRPN_BASECLASS
 
#include <stdio.h> // for NULL, fprintf, stderr, FILE
 
#include "vrpn_Configure.h" // for VRPN_API, VRPN_CALLBACK
#include "vrpn_Connection.h"
#include "vrpn_Shared.h" // for timeval, vrpn_gettimeofday
#include "vrpn_Types.h"  // for vrpn_int32, vrpn_uint32
 
/*
-----------------------------------------------------------------------------
Answer to the question:
   "Why is there both a UNIQUE and NON-UNIQUE base class?",
   or
   "Why can't everything from vrpn_BaseClass be moved into
vrpn_BaseClassUnique?"
 
   The first reason is that removing vrpn_BaseClass would require the
   vrpn_BaseClassUnique constructor to take a name and connection object as
   parameters, which would cause some problems due to the way virtual base
   classes are implemented in C++.
 
   Any class that inherits from a virtual base (either directly or several
   generations removed) must provide an explicit call to the constructor
   of the virtual base.  This is done because the virtual base constructor
   is invoked from the very first class in the constructor chain.
 
   Take for example vrpn_Tng3, which inherits vrpn_Button and vrpn_Serial_Analog
   (and thus vrpn_Analog).  Creating a new instance of a vrpn_Tng3 object will
   call the constructors in this order:
       Tng3
       BaseClassUnique  (because it is a virtual base)
       Button
       BaseClass   (coming from Button)
       Serial_Analog
       Analog
       BaseClass   (coming from Analog)
 
   Right now, BaseClassUnique's constructor has no parameters.  So the
   Tng3 constructor does not have to explicitly invoke BaseClassUnique, although
   implicitly it will call BaseClassUnique's 0-parameter constructor before
   doing anything else.  But if BaseClass is eliminated, then BaseClassUnique's
   constructor must do the work of creating the connection and copying the
   service name.  So BaseClassUnique's constructor must now take a couple
   parameters, which means that every class (including Tng3, Button, Analog, and
Serial_Analog) would have to explicitly name the constructor for BaseClassUnique
in the code and specify parameters for connection and service-name, even though
only one such call to the BaseClassUnique's constructor would ever actually
occur at runtime (that of Tng3 since it's located at the lowest level of the
family tree; the rest of the calls would be ignored).  This would mean inserting
"vrpn_BaseClassUnique(name,connection)" into the initializer section of every
constructor in *every* class under the BaseClassUnique subtree.
 
   The second reason we have both a unique and non-unique base class is that
   the "register_types" virtual function must be called several times for
   multiply-inherited devices, with a different virtual target in each case.
   Presently, register_types() is called from vrpn_BaseClass::init().
   init() may be called multiple times using a different vftable entry for
   register_types() each time (e.g. for the Tng3 it will refer once to
   vrpn_Analog::register_types() and once to vrpn_Button::register_types()).
   Both init() and the pure-virtual declaration of register_types() are found
   in BaseClass.  Moving init() up into BaseClassUnique instead of BaseClass
   means that register_types() would have to move up as well.  And if
   register_types() is declared in the virtual base class, BaseClassUnique,
   it can only have one virtual target.
 
   So it might appear that vrpn_BaseClass has no data members and would
   therefore be easy to eliminate.  However it actually does have a data
   member: the vftable entry for "register_types".  And this data member
   *must* be duplicated in the case of multiply-inherited device because a
   single object will need several distinct virtual targets for
   "register_types".
 
   [Jeff Feasel  19 May 2005]
-----------------------------------------------------------------------------
*/
 
const int vrpn_MAX_BCADRS = 100;

typedef enum {
    vrpn_TEXT_NORMAL = 0,
    vrpn_TEXT_WARNING = 1,
    vrpn_TEXT_ERROR = 2
} vrpn_TEXT_SEVERITY;
const unsigned vrpn_MAX_TEXT_LEN = 1024;
 
class VRPN_API vrpn_BaseClass;

// It is a system class, with one instance of it in existence.  Each object in
// the system registers with this class when it is constructed.  By default,
// this class prints all Warning and Error messages to stdout, prefaced by
// "vrpn Warning(0) from MUMBLE: ", where the 0 indicates the level of the
// message and Warning the severity, and MUMBLE the name of the object that sent
// the message. The user could create their own TextPrinter, and attach whatever
// objects they want to it.
//  NOTE: Because there is a vrpn_System_TextPrinter that all vrpn_BaseClass
// objects talk to, and because those objects may be in multiple threads, the
// vrpn_TextPrinter class has to be thread-safe.  This requires all user-
// callable methods to be thread-safe because the destructor may be called
// during a method call.
 
class VRPN_API vrpn_TextPrinter {
public:
    vrpn_TextPrinter();
    ~vrpn_TextPrinter();

    int add_object(vrpn_BaseClass *o);

    void remove_object(vrpn_BaseClass *o);

    void set_min_level_to_print(vrpn_TEXT_SEVERITY severity,
                                vrpn_uint32 level = 0);

    void set_ostream_to_use(FILE *o);
 
protected:
    vrpn_Semaphore d_semaphore;

    class VRPN_API vrpn_TextPrinter_Watch_Entry {
    public:
        vrpn_BaseClass *obj; 
        vrpn_TextPrinter *me;
        vrpn_TextPrinter_Watch_Entry *next;
    };
    vrpn_TextPrinter_Watch_Entry *d_first_watched_object;
 
    FILE *d_ostream;                        
    vrpn_TEXT_SEVERITY d_severity_to_print; 
    vrpn_uint32 d_level_to_print;           

    static int VRPN_CALLBACK
    text_message_handler(void *userdata, vrpn_HANDLERPARAM p);
};
// SWIG does not like this declaration.
#ifndef SWIG
extern VRPN_API vrpn_TextPrinter &vrpn_System_TextPrinter;
#endif

class VRPN_API vrpn_BaseClassUnique {
    friend class VRPN_API vrpn_TextPrinter;
 
public:
    vrpn_BaseClassUnique();
    virtual ~vrpn_BaseClassUnique();

    vrpn_Connection *connectionPtr() { return d_connection; };
 
    bool shutup; // if True, don't print the "No response from server" messages.
 
    friend class SendTextMessageBoundCall;
    class SendTextMessageBoundCall {
    private:
        vrpn_BaseClassUnique *_p;
        vrpn_TEXT_SEVERITY _severity;
 
    public:
        SendTextMessageBoundCall(vrpn_BaseClassUnique *device,
                                 vrpn_TEXT_SEVERITY type)
            : _p(device)
            , _severity(type)
        {
        }
 
        int operator()(const char *msg) const
        {
            struct timeval timestamp;
            vrpn_gettimeofday(&timestamp, NULL);
            return _p->send_text_message(msg, timestamp, _severity);
        }
    };
 
protected:
    vrpn_Connection *d_connection; 
    char *d_servicename; 
 
    vrpn_int32 d_sender_id;       
    vrpn_int32 d_text_message_id; 
    vrpn_int32 d_ping_message_id; 
    vrpn_int32 d_pong_message_id; 

    // This is a wrapper for the vrpn_Connection call that registers
    // message handlers.  It should be used rather than the connection's
    // function because this one will remember to unregister all of its handlers
    // at object deletion time.
    int register_autodeleted_handler(vrpn_int32 type,
                                     vrpn_MESSAGEHANDLER handler,
                                     void *userdata,
                                     vrpn_int32 sender = vrpn_ANY_SENDER);

    static int encode_text_message_to_buffer(char *buf,
                                             vrpn_TEXT_SEVERITY severity,
                                             vrpn_uint32 level,
                                             const char *msg);

    static int decode_text_message_from_buffer(char *msg,
                                               vrpn_TEXT_SEVERITY *severity,
                                               vrpn_uint32 *level,
                                               const char *buf);

    int send_text_message(const char *msg, struct timeval timestamp,
                          vrpn_TEXT_SEVERITY type = vrpn_TEXT_NORMAL,
                          vrpn_uint32 level = 0);

    SendTextMessageBoundCall
    send_text_message(vrpn_TEXT_SEVERITY type = vrpn_TEXT_NORMAL)
    {
        return SendTextMessageBoundCall(this, type);
    }

    void server_mainloop(void);

    void client_mainloop(void);
 
private:
    struct {
        vrpn_MESSAGEHANDLER handler;
        vrpn_int32 sender;
        vrpn_int32 type;
        void *userdata;
    } d_handler_autodeletion_record[vrpn_MAX_BCADRS];
    int d_num_autodeletions;
 
    int d_first_mainloop; 
    struct timeval d_time_first_ping; 
    struct timeval
        d_time_last_warned; 
    int d_unanswered_ping;  
    int d_flatline;         

    static int VRPN_CALLBACK handle_ping(void *userdata, vrpn_HANDLERPARAM p);
    static int VRPN_CALLBACK handle_pong(void *userdata, vrpn_HANDLERPARAM p);
    static int VRPN_CALLBACK
    handle_connection_dropped(void *userdata, vrpn_HANDLERPARAM p);
    void initiate_ping_cycle(void);
};
 
//---------------------------------------------------------------
 
class VRPN_API vrpn_BaseClass : virtual public vrpn_BaseClassUnique {
 
public:
    vrpn_BaseClass(const char *name, vrpn_Connection *c = NULL);
 
    virtual ~vrpn_BaseClass();

    virtual void mainloop() = 0;
 
protected:
    virtual int init(void);

    virtual int register_senders(void);

    virtual int register_types(void) = 0;
};
 
//---------------------------------------------------------------
// Within VRPN (and other libraries), it is wise to avoid using the
// Standard Template Library.  This is very annoying, but required
// by the fact that some systems have incompatible versions of STL.
// This caused problems with any program that uses the GHOST library
// (which had its own STL on Windows), and I've heard tell of problems
// with other systems as well.  On the other hand, nothing says that
// we can't have our OWN template types and use them.  This next type
// is used to handle callback lists within objects.  It is templated
// over the struct that is passed to the user callback.
// See vrpn_Button.h's usage for an example.
 
// Disables a warning that the class requires DLL linkage to be
// used by clients of classes that include one: The classes themselves
// have DLL linkage, the code below asks for (but apparently does not
// get) DLL linkage, and the DLL-linked test programs work when things
// are as they are.  Do not use this class outside of a derived class.
#ifdef _MSC_VER
#pragma warning(disable : 4251)
#endif
template <class CALLBACK_STRUCT> class VRPN_API vrpn_Callback_List {
public:
    typedef void(VRPN_CALLBACK *HANDLER_TYPE)(void *userdata,
                                              const CALLBACK_STRUCT info);

    int register_handler(void *userdata, HANDLER_TYPE handler)
    {
        CHANGELIST_ENTRY *new_entry;
 
        // Ensure that the handler is non-NULL
        if (handler == NULL) {
            fprintf(stderr,
                    "vrpn_Callback_List::register_handler(): NULL handler\n");
            return -1;
        }
 
        // Allocate and initialize the new entry
        try {
          new_entry = new CHANGELIST_ENTRY;
        } catch (...) {
          fprintf(stderr,
            "vrpn_Callback_List::register_handler(): Out of memory\n");
          return -1;
        }
        new_entry->handler = handler;
        new_entry->userdata = userdata;
 
        // Add this handler to the chain at the beginning (don't check to see
        // if it is already there, since duplication is okay).
        new_entry->next = d_change_list;
        d_change_list = new_entry;
 
        return 0;
    };

    int unregister_handler(void *userdata, HANDLER_TYPE handler)
    {
        // The pointer at *snitch points to victim
        CHANGELIST_ENTRY *victim, **snitch;
 
        // Find a handler with this registry in the list (any one will do,
        // since all duplicates are the same).
        snitch = &d_change_list;
        victim = *snitch;
        while ((victim != NULL) && ((victim->handler != handler) ||
                                    (victim->userdata != userdata))) {
            snitch = &((*snitch)->next);
            victim = victim->next;
        }
 
        // Make sure we found one
        if (victim == NULL) {
            fprintf(
                stderr,
                "vrpn_Callback_List::unregister_handler: No such handler\n");
            return -1;
        }
 
        // Remove the entry from the list
        *snitch = victim->next;
        try {
          delete victim;
        } catch (...) {
          fprintf(stderr, "vrpn_Callback_List::unregister_handler: delete failed\n");
          return -1;
        }
 
        return 0;
    };

    void call_handlers(const CALLBACK_STRUCT &info)
    {
        CHANGELIST_ENTRY *handler = d_change_list;
        while (handler != NULL) {
            handler->handler(handler->userdata, info);
            handler = handler->next;
        }
    };

    vrpn_Callback_List()
        : d_change_list(NULL){};

    vrpn_Callback_List(const vrpn_Callback_List& from)
      : d_change_list(NULL)
    {
      // Copy all elements from the other list.  XXX Side effect, this inverts
      // the order
      CHANGELIST_ENTRY *current, *next;
      current = from.d_change_list;
      while (current != NULL) {
        register_handler(current->userdata, current->handler);
        current = current->next;
      }
    }
 
    void operator=(const vrpn_Callback_List& from)
    {
      // Delete any existing elements in the list.
      CHANGELIST_ENTRY* current, * next;
      current = d_change_list;
      while (current != NULL) {
        next = current->next;
        try {
          delete current;
        }
        catch (...) {
          fprintf(stderr,
            "vrpn_Callback_List::operator =: Deletion failure\n");
          return;
        }
        current = next;
      }
 
      // Copy all elements from the other list.  XXX Side effect, this inverts
      // the order
      current = from.d_change_list;
      while (current != NULL) {
        register_handler(current->userdata, current->handler);
        current = current->next;
      }
    }

    ~vrpn_Callback_List()
    {
        while (d_change_list != NULL) {
            CHANGELIST_ENTRY *next = d_change_list->next;
            try {
              delete d_change_list;
            } catch (...) {
              fprintf(stderr, "vrpn_Callback_List::~vrpn_Callback_List: delete failed\n");
              return;
            }
            d_change_list = next;
        }
    };
 
protected:
    typedef struct vrpn_CBS {
        void *userdata;
        HANDLER_TYPE handler;
        struct vrpn_CBS *next;
    } CHANGELIST_ENTRY;
    CHANGELIST_ENTRY *d_change_list;
};
 
// End of defined VRPN_BASECLASS for vrpn_BaseClass.h
#endif