Deprecation warnings for features that will disappear (fixes #552)

examples/MyModule/mymodule.cpp

@@ -36,6 +36,7 @@
 #include "dynamicloader.h"
 #include "exceptions.h"
 #include "genericmodel.h"
+#include "genericmodel_impl.h"
 #include "kernel_manager.h"
 #include "model.h"
 #include "model_manager_impl.h"

lib/sli/misc_helpers.sli

@@ -38,7 +38,7 @@ Synopsis:
 Priority (From) (Message) message ->
 
 where "Priority" may be any positive integer, or one of the following:
-M_DEBUG, M_STATUS, M_INFO, M_WARNING, M_ERROR, M_FATAL
+M_DEBUG, M_STATUS, M_INFO, M_DEPRECATED, M_WARNING, M_ERROR, M_FATAL
 
 Description: 
 Display a message, if priority is higher than current verbosity-level. 
@@ -87,15 +87,19 @@ Examples: Short form:
               issues something like
           % Jul 21 16:24:12 SLI[10] Your last action had no effect 
 
-          4. (Result may be invalid) M_WARNING message
+          4. (Function is deprecated) M_DEPRECATED message
+              issues something like
+          % Jul 21 16:24:12 SLI[18] Function is deprecated 
+
+          5. (Result may be invalid) M_WARNING message
               issues something like
           % Jul 21 16:24:24 SLI[20] Result may be invalid  
 
-          5. (This should never happen!) M_ERROR message
+          6. (This should never happen!) M_ERROR message
               issues something like
           % Jul 21 16:24:36 SLI[30] This should never happen!
 
-          6. (It's all broken, let's go home.) M_FATAL message
+          7. (It's all broken, let's go home.) M_FATAL message
               issues something like
           % Jul 21 16:24:36 SLI[40] It's all broken, let's go home.
 
@@ -116,15 +120,16 @@ FirstVersion: Apr 9 1999
 Remarks: 
          M_* values are defined in system dictionary.
          You may introduce new priority levels in the user dictionary if convenient.
-         Standard values are: M_ALL    = 0
-                              M_DEBUG   = 5
-                              M_STATUS  = 7
-                              M_INFO    = 10
-                              M_WARNING = 20
-                              M_ERROR   = 30
-                              M_FATAL   = 40
-                              M_QUIET   = 100
-         Standard output:     M_OUT     = cout
+         Standard values are: M_ALL        = 0
+                              M_DEBUG      = 5
+                              M_STATUS     = 7
+                              M_INFO       = 10
+                              M_DEPRECATED = 18
+                              M_WARNING    = 20
+                              M_ERROR      = 30
+                              M_FATAL      = 40
+                              M_QUIET      = 100
+         Standard output:     M_OUT        = cout
 
 SeeAlso: setverbosity
 */
@@ -134,14 +139,15 @@ systemdict begin %this is unnessessary, if misc_helpers.sli is called from sli-i
   %               but that's not sure, and it won't harm anyway...
 
   %Define error levels:
-  /M_ALL      0 def
-  /M_DEBUG    5 def
-  /M_STATUS   7 def
-  /M_INFO    10 def
-  /M_WARNING 20 def
-  /M_ERROR   30 def
-  /M_FATAL   40 def
-  /M_QUIET  100 def
+  /M_ALL        0 def
+  /M_DEBUG      5 def
+  /M_STATUS     7 def
+  /M_INFO       10 def
+  /M_DEPRECATED 18 def
+  /M_WARNING    20 def
+  /M_ERROR      30 def
+  /M_FATAL      40 def
+  /M_QUIET      100 def
 
 end %systemdict
 
@@ -170,6 +176,7 @@ VerbosityLevel setverbosity -> -
 M_DEBUG        setverbosity -> -
 M_STATUS       setverbosity -> -
 M_INFO         setverbosity -> -
+M_DEPRECATED   setverbosity -> -
 M_WARNING      setverbosity -> -
 M_ERROR        setverbosity -> -
 M_FATAL        setverbosity -> -
@@ -190,6 +197,7 @@ Parameters:
      M_DEBUG=5,  display debugging messages and above
      M_STATUS=7,  display status messages and above
      M_INFO=10, display information messages and above
+     M_DEPRECATED=18, display deprecation warnings and above
      M_WARNING=20, display warning messages and above
      M_ERROR=30, display error messages and above
      M_FATAL=40, display failure messages and above
@@ -223,6 +231,7 @@ Remarks:
                        M_DEBUG   = 5
                        M_STATUS  = 7
                        M_INFO    = 10
+                       M_DEPRECATED = 18
                        M_WARNING = 20
                        M_ERROR   = 30
                        M_FATAL   = 40

lib/sli/nest-init.sli

@@ -732,9 +732,18 @@ def
    SeeAlso: Create, LayoutArray
 */
 
+/LayoutNetwork
+<< /deprecation_warning true >>
+Options
+
 /LayoutNetwork_l_a_dict
 {
   << >> begin
+  /LayoutNetwork /deprecation_warning GetOption true eq
+  {
+    (SLI function LayoutNetwork is deprecated in NEST 3.0.) M_DEPRECATED message
+    /LayoutNetwork << /deprecation_warning false >> SetOptions
+  } if
              /val   Set
   size       /n_dim Set
    dup 0 get /n     Set
@@ -775,6 +784,11 @@ def
 /LayoutNetwork_l_a
 {
   << >> begin
+  /LayoutNetwork /deprecation_warning GetOption true eq
+  {
+    (SLI function LayoutNetwork is deprecated in NEST 3.0.) M_DEPRECATED message
+    /LayoutNetwork << /deprecation_warning false >> SetOptions
+  } if
   size       /n_dim Set
    dup 0 get /n     Set
              /dim   Set
@@ -1222,22 +1236,6 @@ def
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-/GetNetwork_i_i {
-  << >> begin
-  /depth Set
-  dup
-  GetStatus /model get % id model
-  /subnet eq depth 1 geq and {       % id
-    dup                % id id
-    [
-      exch           % id [ id
-      GetGlobalChildren { depth 1 sub GetNetwork_i_i } forall
-    ]
-    exch prepend
-  } if
-  end
-} def
-
 /* BeginDocumentation
 Name: GetNetwork - Return a nested list with the IDs of nodes in a multi-dimensional subnet.
 Synpsis: ID n GetNetwork -> [ ]
@@ -1261,6 +1259,32 @@ and can thus take a lot of time and consume huge amounts of memory.
 
 SeeAlso: GetGlobalNodes, GetLocalNodes, GetGlobalLeaves, GetLocalLeaves, GetGlobalChildren, GetLocalChildren
 */
+
+/GetNetwork
+<< /deprecation_warning true >>
+Options
+
+/GetNetwork_i_i {
+  << >> begin
+  /GetNetwork /deprecation_warning GetOption true eq
+  {
+    (SLI function GetNetwork is deprecated in NEST 3.0.) M_DEPRECATED message
+    /GetNetwork << /deprecation_warning false >> SetOptions
+  } if
+  /depth Set
+  dup
+  GetStatus /model get % id model
+  /subnet eq depth 1 geq and {       % id
+    dup                % id id
+    [
+      exch           % id [ id
+      GetGlobalChildren { depth 1 sub GetNetwork_i_i } forall
+    ]
+    exch prepend
+  } if
+  end
+} def
+
 /GetNetwork trie
 [/integertype /integertype] /GetNetwork_i_i load addtotrie
 def

libnestutil/logging.h

@@ -56,6 +56,7 @@ enum severity_t
   M_DEBUG = 5,
   M_STATUS = 7,
   M_INFO = 10,
+  M_DEPRECATED = 18,
   M_WARNING = 20,
   M_ERROR = 30,
   M_FATAL = 40,

libnestutil/logging_event.cpp

@@ -63,6 +63,9 @@ std::ostream& operator<<( std::ostream& out, const LoggingEvent& e )
   case M_INFO:
     out << "[INFO] ";
     break;
+  case M_DEPRECATED:
+    out << "[DEPRECATED] ";
+    break;
   case M_WARNING:
     out << "[WARNING] ";
     break;

models/modelsmodule.cpp

@@ -36,6 +36,9 @@
 
 #include "modelsmodule.h"
 
+// Includes from nestkernel
+#include "genericmodel_impl.h"
+
 // Generated includes:
 #include "config.h"
 
@@ -173,7 +176,9 @@ ModelsModule::commandstring( void ) const
 void
 ModelsModule::init( SLIInterpreter* )
 {
-  kernel().model_manager.register_node_model< iaf_neuron >( "iaf_neuron" );
+  kernel().model_manager.register_node_model< iaf_neuron >( "iaf_neuron",
+    /* private_model */ false,
+    /* deprecation_info */ "NEST 3.0" );
   kernel().model_manager.register_node_model< iaf_chs_2007 >( "iaf_chs_2007" );
   kernel().model_manager.register_node_model< iaf_psc_alpha >(
     "iaf_psc_alpha" );
@@ -353,7 +358,9 @@ ModelsModule::init( SLIInterpreter* )
 
   // This version of the AdEx model does not depend on GSL.
   kernel().model_manager.register_node_model< aeif_cond_alpha_RK5 >(
-    "aeif_cond_alpha_RK5" );
+    "aeif_cond_alpha_RK5",
+    /*private_model*/ false,
+    /*deprecation_info*/ "NEST 3.0" );
 
 #ifdef HAVE_MUSIC
   //// proxies for inter-application communication using MUSIC

nest/neststartup.cpp

@@ -41,6 +41,7 @@
 
 // Includes from nestkernel:
 #include "dynamicloader.h"
+#include "genericmodel_impl.h"
 #include "kernel_manager.h"
 #include "nest.h"
 #include "nestmodule.h"

nestkernel/genericmodel.h

@@ -44,8 +44,7 @@ template < typename ElementT >
 class GenericModel : public Model
 {
 public:
-  GenericModel( const std::string& );
-  GenericModel( const char[] );
+  GenericModel( const std::string&, const std::string& deprecation_info );
 
   /**
    * Create copy of model with new name.
@@ -85,6 +84,8 @@ class GenericModel : public Model
 
   void set_model_id( int );
 
+  void deprecation_warning( const std::string& );
+
 private:
   void set_status_( DictionaryDatum );
   DictionaryDatum get_status_();
@@ -105,20 +106,25 @@ class GenericModel : public Model
    * Prototype node from which all instances are constructed.
    */
   ElementT proto_;
+
+  /**
+   * String containing deprecation information; empty if model not deprecated.
+   */
+  std::string deprecation_info_;
+
+  /**
+   * False until deprecation warning has been issued once
+   */
+  bool deprecation_warning_issued_;
 };
 
 template < typename ElementT >
-GenericModel< ElementT >::GenericModel( const std::string& name )
+GenericModel< ElementT >::GenericModel( const std::string& name,
+  const std::string& deprecation_info )
   : Model( name )
   , proto_()
-{
-  set_threads();
-}
-
-template < typename ElementT >
-GenericModel< ElementT >::GenericModel( const char name[] )
-  : Model( std::string( name ) )
-  , proto_()
+  , deprecation_info_( deprecation_info )
+  , deprecation_warning_issued_( false )
 {
   set_threads();
 }
@@ -128,6 +134,8 @@ GenericModel< ElementT >::GenericModel( const GenericModel& oldmod,
   const std::string& newname )
   : Model( newname )
   , proto_( oldmod.proto_ )
+  , deprecation_info_( oldmod.deprecation_info_ )
+  , deprecation_warning_issued_( false )
 {
   set_type_id( oldmod.get_type_id() );
   set_threads();

nestkernel/genericmodel_impl.h

@@ -0,0 +1,52 @@
+/*
+ *  genericmodel_impl.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 GENERICMODEL_IMPL_H
+#define GENERICMODEL_IMPL_H
+
+#include "genericmodel.h"
+
+// Includes from nestkernel:
+#include "kernel_manager.h"
+#include "logging_manager.h"
+
+namespace nest
+{
+
+template < typename ElementT >
+void
+GenericModel< ElementT >::deprecation_warning( const std::string& caller )
+{
+  if ( deprecation_warning_issued_ or deprecation_info_.empty() )
+    return;
+
+  if ( not deprecation_info_.empty() )
+  {
+    LOG( M_DEPRECATED,
+      caller,
+      "Model " + get_name() + " is deprecated in " + deprecation_info_ + "." );
+  }
+
+  deprecation_warning_issued_ = true;
+}
+}
+#endif

nestkernel/kernel_manager.h

@@ -23,13 +23,11 @@
 #ifndef KERNEL_MANAGER_H
 #define KERNEL_MANAGER_H
 
-// Includes from libnestutil:
-#include "logging_manager.h"
-
 // Includes from nestkernel:
 #include "connection_manager.h"
 #include "event_delivery_manager.h"
 #include "io_manager.h"
+#include "logging_manager.h"
 #include "model_manager.h"
 #include "modelrange_manager.h"
 #include "mpi_manager.h"