music_message_in_proxy.h

Go to the documentation of this file.

/*
 *  music_message_in_proxy.h
 *
 *  This file is part of NEST.
 *
 *  Copyright (C) 2004 The NEST Initiative
 *
 *  NEST is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  NEST is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with NEST.  If not, see <http://www.gnu.org/licenses/>.
 *
 */
 
#ifndef MUSIC_MESSAGE_IN_PROXY_H
#define MUSIC_MESSAGE_IN_PROXY_H
 
// Generated includes:
#include "config.h"
 
#ifdef HAVE_MUSIC
 
// C includes:
#include <mpi.h>
 
// C++ includes:
#include <string>
#include <vector>
 
// Includes from libnestutil:
#include "dict_util.h"
 
// External includes:
#include <music.hh>
 
// Includes from nestkernel:
#include "device_node.h"
#include "nest_types.h"
 
 
namespace nest
{
void register_music_message_in_proxy( const std::string& name );
 
/* BeginUserDocs: device, MUSIC
 
Short description
+++++++++++++++++
 
A device which receives message strings from MUSIC
 
Description
+++++++++++
 
A ``music_message_in_proxy`` can be used to receive message strings from
remote MUSIC applications in NEST.
 
It uses the MUSIC library to receive message strings from other
applications. The ``music_message_in_proxy`` represents an input port to
which MUSIC can connect a message source. The ``music_message_in_proxy``
can queried using GetStatus to retrieve the messages.
 
To clear the data array, the parameter ``n_messages`` can be set to 0.
 
This model is only available if NEST was compiled with MUSIC.
 
Parameters
++++++++++
 
The following properties are available in the status Dictionary:
 
============ ======= =========================================================
 port_name   string  The name of the MUSIC input port to listen to (default:
                     message_in)
 port_width  integer The width of the MUSIC input port
 data        array   A sub-Dictionary that contains the string messages
                     in the form of two arrays:
                     messages      - The strings
                     message_times - The times the messages were sent (ms)
 n_messages  integer The number of messages
 published   boolean A bool indicating if the port has been already published
                     with MUSIC
============ ======= =========================================================
 
See also
++++++++
 
music_event_out_proxy, music_event_in_proxy, music_cont_in_proxy
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: music_message_in_proxy
 
EndUserDocs */
 
class MsgHandler : public MUSIC::MessageHandler
{
  std::vector< std::string > messages;  
  std::vector< double > message_times;  
 
  void
  operator()( double t, void* msg, size_t size )
  {
    message_times.push_back( t * 1000.0 );
    messages.push_back( std::string( static_cast< char* >( msg ), size ) );
  }
 
public:
  void
  get_status( Dictionary& d ) const
  {
    Dictionary dict;
    dict[ names::messages ] = messages;
    dict[ names::message_times ] = std::vector< double >( message_times );
    d[ names::n_messages ] = static_cast< long >( messages.size() );
    d[ names::data ] = dict;
  }
 
  void
  clear()
  {
    message_times.clear();
    messages.clear();
  }
};
 
class music_message_in_proxy : public DeviceNode
{
 
public:
  music_message_in_proxy();
  music_message_in_proxy( const music_message_in_proxy& );
 
  bool
  has_proxies() const
  {
    return false;
  }
  bool
  one_node_per_process() const
  {
    return true;
  }
 
  void get_status( Dictionary& ) const;
  void set_status( const Dictionary& );
 
private:
  void init_buffers_();
  void pre_run_hook();
 
  void
  update( Time const&, const long, const long )
  {
  }
 
  // ------------------------------------------------------------
  struct State_;
 
  struct Parameters_
  {
    std::string port_name_;      
    double acceptable_latency_;  
 
    Parameters_();  
 
    void get( Dictionary& ) const;
 
    void set( const Dictionary&, State_&, Node* );
  };
 
  // ------------------------------------------------------------
 
  struct State_
  {
    bool published_;  
    int port_width_;  
 
    State_();  
 
    void get( Dictionary& ) const;  
    void set( const Dictionary&, const Parameters_&, Node* );
  };
 
  // ------------------------------------------------------------
 
  struct Buffers_
  {
    MsgHandler message_handler_;
  };
 
  // ------------------------------------------------------------
 
  struct Variables_
  {
    MUSIC::MessageInputPort* MP_;  
  };
 
  // ------------------------------------------------------------
 
  Parameters_ P_;
  State_ S_;
  Buffers_ B_;
  Variables_ V_;
};
 
inline void
music_message_in_proxy::get_status( Dictionary& d ) const
{
  P_.get( d );
  S_.get( d );
 
  B_.message_handler_.get_status( d );
}
 
inline void
music_message_in_proxy::set_status( const Dictionary& d )
{
  Parameters_ ptmp = P_;    // temporary copy in case of errors
  ptmp.set( d, S_, this );  // throws if BadProperty
 
  State_ stmp = S_;
  stmp.set( d, P_, this );  // throws if BadProperty
 
  long nm = 0;
  if ( update_value_param( d, names::n_messages, nm, this ) )
  {
    if ( nm == 0 )
    {
      B_.message_handler_.clear();
    }
    else
    {
      throw BadProperty( "n_messaged can only be set to 0." );
    }
  }
 
  // if we get here, temporaries contain consistent set of properties
  P_ = ptmp;
  S_ = stmp;
}
 
}  // namespace
 
#endif
 
#endif /* #ifndef MUSIC_MESSAGE_IN_PROXY_H */