ConnectionBase Class Reference

ConnectionBase and Connection<Tag> are part of the POOMA external data connection API. More...

#include <Connection.h>

Inheritance diagram for ConnectionBase:

Inheritance graph
[legend]
Collaboration diagram for ConnectionBase:

Collaboration graph
[legend]

List of all members.

Public Types

enum  { disconnectEvent = 0, connectEvent = 1 }
 Enumeration of event types used to notify connectors. More...
enum  { in = 0, out = 1, inout = 2 }
 Enumeration of data transfer directions. More...
typedef std::vector
< ConnectorBase * > 
List_t
typedef List_t::size_type Size_t
typedef List_t::iterator iterator
typedef List_t::const_iterator const_iterator

Public Member Functions

 ConnectionBase (const char *conname, const char *contype)
 The constructor takes the strings for the name and type.
virtual ~ConnectionBase ()
 When destructed, a ConnectionBase disconnects all Connectors and then deletes them.
virtual ConnectorBaseconnect (ConnectorBase *)
 Establish a connection from the first argument to the second.
virtual ConnectorBasedisconnect (ConnectorBase *)
 Disconnect an existing Connector, but do not delete it.
virtual void update (ConnectorBase *=0)
 Update the connections - tell the connections to update, or just an individual one.
virtual void interact (const char *=0)
 Allow for interaction with the connection.
virtual void close ()
 Completely close the connection and remove all connectors.
virtual bool connected () const
 Return whether we are connected properly right now.
const std::string & name () const
 Return the name of this connection.
const std::string & type () const
 Return the type string of this connection.
Size_t size () const
 Return the number of registered connectors.
Begin/end iterators for the list of connectors
iterator begin ()
iterator end ()
Const begin/end iterators for the list of connectors
const_iterator begin () const
const_iterator end () const

Protected Member Functions

void disconnectConnectors ()
 Disconnect any remaining connectors.


Detailed Description

ConnectionBase and Connection<Tag> are part of the POOMA external data connection API.

The other part of this API are the classes ConnectorBase and Connector<T,Tag>.

Connection<Tag> represents the information about how a "connection" is made to some external agency. Examples: files, Paws-based programs, visualization facilities. The parameter "Tag" is a simple tag class used to partially specialize Connection. This same tag is used in Connector.

Connector<T,Tag> represents the information about how to map data from a single instance of a type T to some Connection<Tag> object. For example, if data must be serialized into a buffer and an API routine for the "Tag" connection type called, Connector<T,Tag> will do that, for a given instance of T.

There can be several Connector<T,Tag> objects associated with a given Connection<Tag>. Each object maintains the "channel" for a data object to the connection. The connection object stores a list of connectors and provides an API for "updating" and "interacting" with the external agency.

ConnectionBase is a non-templated base class that provides some general facilities for Connection<Tag> objects. It does the following:

  1. Stores a (heterogeneous) list of connectors, by storing a list of pointers to the base class for all connectors, ConnectorBase.
  2. Provides an API to:
    • iterate over connectors
    • update all connectors
    • interact with the connection
    • disconnect connectors
    • close the connection
  3. Provides storage for a user-supplied name string for the connection.
  4. Provides storage for a user-supplied type string for the connection.

New connector's are added via a "connect" method in ConnectionBase. You can create your own Connector<T,Tag> instance, and add that in via connect(), or you can call a specialized (and generally templated) connect() method in the Connection<Tag> class. Most Connection classes provide the specialized connect in order to make it nicer to add in new connectors without having to instantiate a Connector<T,Tag> directly in user code.

When you update the connections, you ask each connector to do an update. Updates are done in the order they were connected. Each connector has a transfer mode, one of the following:

The transfer mode is established when the connector is added. An update causes new values to be imported or exported based on the current state of the data and the external agency. For a visualization connection, an update would result in new data being sent to the renderer and hopefully a new image drawn in the visualization program's display windows(s). You can update all connectors attached to a connection, or just one (by providing a pointer to the ConnectorBase of the connection you want to update).

You can disconnect all or specific connectors via the disconnect() method. This will remove that connector's data from the external agency, and future update() calls will not use that connector.

To completely shut down the connection, either delete the connector instance or call the close() method. It will disconnect all connectors, and shut down the connection (for a visualizer, this would close the windows; for a Paws connection, it will close the connection to the Paws controller).

Some external agencies may need to occasionally take control, to do some event processing or something. The interact() method allows this to happen. It may not be necessary for some connections.


Member Typedef Documentation

typedef std::vector<ConnectorBase *> ConnectionBase::List_t

typedef List_t::size_type ConnectionBase::Size_t

typedef List_t::iterator ConnectionBase::iterator

typedef List_t::const_iterator ConnectionBase::const_iterator


Member Enumeration Documentation

anonymous enum

Enumeration of event types used to notify connectors.

Enumerator:
disconnectEvent 
connectEvent 

anonymous enum

Enumeration of data transfer directions.

Enumerator:
in 
out 
inout 


Constructor & Destructor Documentation

ConnectionBase::ConnectionBase ( const char *  conname,
const char *  contype 
)

The constructor takes the strings for the name and type.

virtual ConnectionBase::~ConnectionBase (  )  [virtual]

When destructed, a ConnectionBase disconnects all Connectors and then deletes them.


Member Function Documentation

virtual ConnectorBase* ConnectionBase::connect ( ConnectorBase  )  [virtual]

Establish a connection from the first argument to the second.

The first should be Connect a new Connector. The Connector maps from a single data object (such as a Field) to this ConnectionBase. The base class pointer is used to store the data, since Connector is a templated class. The user must 'new' thie Connector object and give the allocated instance to this class, which will delete the instance when the connection closes. Return the ConnectorBase pointer just connected.

Referenced by Connection< Paws >::connect(), Connection< Lux >::connect(), and Connection< Paws >::connectScalar().

virtual ConnectorBase* ConnectionBase::disconnect ( ConnectorBase  )  [virtual]

Disconnect an existing Connector, but do not delete it.

This removes the connector from our list, and informs it it should not use the ConnectionBase anymore. ConnectorBase must implement a 'notify(int)' virtual function. Return the ConnectorBase pointer just disconnected.

Referenced by ConnectorBase::~ConnectorBase().

virtual void ConnectionBase::update ( ConnectorBase = 0  )  [virtual]

Update the connections - tell the connections to update, or just an individual one.

virtual void ConnectionBase::interact ( const char *  = 0  )  [virtual]

Allow for interaction with the connection.

An optional string can be provided to tell how to do the interaction.

Reimplemented in Connection< Lux >.

virtual void ConnectionBase::close (  )  [virtual]

Completely close the connection and remove all connectors.

This is the equivalent of running the destructor, using this routine you can control when the connection is closed. By default it just removes all connectors.

Reimplemented in Connection< Lux >, and Connection< Paws >.

virtual bool ConnectionBase::connected (  )  const [virtual]

Return whether we are connected properly right now.

Reimplemented in Connection< Lux >, and Connection< Paws >.

const std::string& ConnectionBase::name (  )  const [inline]

Return the name of this connection.

const std::string& ConnectionBase::type (  )  const [inline]

Return the type string of this connection.

iterator ConnectionBase::begin (  )  [inline]

iterator ConnectionBase::end (  )  [inline]

const_iterator ConnectionBase::begin (  )  const [inline]

const_iterator ConnectionBase::end (  )  const [inline]

Size_t ConnectionBase::size (  )  const [inline]

Return the number of registered connectors.

void ConnectionBase::disconnectConnectors (  )  [protected]

Disconnect any remaining connectors.


The documentation for this class was generated from the following file:

Generated on Wed Mar 16 06:19:43 2011 for FreePOOMA by  doxygen 1.5.9