1    	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2    	/*                                                                           */
3    	/*                  This file is part of the program and library             */
4    	/*         SCIP --- Solving Constraint Integer Programs                      */
5    	/*                                                                           */
6    	/*  Copyright (c) 2002-2023 Zuse Institute Berlin (ZIB)                      */
7    	/*                                                                           */
8    	/*  Licensed under the Apache License, Version 2.0 (the "License");          */
9    	/*  you may not use this file except in compliance with the License.         */
10   	/*  You may obtain a copy of the License at                                  */
11   	/*                                                                           */
12   	/*      http://www.apache.org/licenses/LICENSE-2.0                           */
13   	/*                                                                           */
14   	/*  Unless required by applicable law or agreed to in writing, software      */
15   	/*  distributed under the License is distributed on an "AS IS" BASIS,        */
16   	/*  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. */
17   	/*  See the License for the specific language governing permissions and      */
18   	/*  limitations under the License.                                           */
19   	/*                                                                           */
20   	/*  You should have received a copy of the Apache-2.0 license                */
21   	/*  along with SCIP; see the file LICENSE. If not visit scipopt.org.         */
22   	/*                                                                           */
23   	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
24   	
25   	/**@file   objtable.h
26   	 * @brief  C++ wrapper for statistics tables
27   	 * @author Tristan Gally
28   	 */
29   	
30   	/*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
31   	
32   	#ifndef __SCIP_OBJTABLE_H__
33   	#define __SCIP_OBJTABLE_H__
34   	
35   	#include <cstring>
36   	#include <utility>
37   	
38   	#include "scip/scip.h"
39   	#include "objscip/objcloneable.h"
40   	namespace scip
41   	{
42   	
43   	/**
44   	 *  @brief C++ wrapper for statistics tables
45   	 *
46   	 *  This class defines the interface for statistics tables implemented in C++. Note that there is a pure virtual function
47   	 *  (this function has to be implemented). This function is: scip_output().
48   	 *
49   	 * - \ref TABLE "Instructions for implementing a statistics table"
50   	 * - \ref TABLES "List of available statistics tables"
51   	 * - \ref type_table.h "Corresponding C interface"
52   	 */
53   	class ObjTable : public ObjCloneable
54   	{
55   	public:
56   	   /*lint --e{1540}*/
57   	
58   	   /** SCIP data structure */
59   	   SCIP* scip_;
60   	
61   	   /** name of the statistics tables */
62   	   char* scip_name_;
63   	
64   	   /** description of the statistics table */
65   	   char* scip_desc_;
66   	
67   	   /** position of the statistics table */
68   	   const int scip_position_;
69   	
70   	   /** output of the statistics table is only printed from this stage onwards */
71   	   SCIP_STAGE scip_earlieststage_;
72   	
73   	   /** default constructor */
74   	   ObjTable(
75   	      SCIP*              scip,               /**< SCIP data structure */
76   	      const char*        name,               /**< name of statistics table */
77   	      const char*        desc,               /**< description of statistics table */
78   	      int                position,           /**< position of statistics table */
79   	      SCIP_STAGE         earlieststage       /**< output of the statistics table is only printed from this stage onwards */
80   	      )
81   	      : scip_(scip),
82   	        scip_name_(0),
83   	        scip_desc_(0),
84   	        scip_position_(position),
85   	        scip_earlieststage_(earlieststage)
86   	   {
87   	      /* the macro SCIPduplicateMemoryArray does not need the first argument: */
88   	      SCIP_CALL_ABORT( SCIPduplicateMemoryArray(scip_, &scip_name_, name, std::strlen(name)+1) );
89   	      SCIP_CALL_ABORT( SCIPduplicateMemoryArray(scip_, &scip_desc_, desc, std::strlen(desc)+1) );
90   	   }
91   	
92   	   /** copy constructor */
93   	   ObjTable(const ObjTable& o) : ObjTable(o.scip_, o.scip_name_, o.scip_desc_, o.scip_position_, o.scip_earlieststage_)
94   	   {
95   	   }
96   	
97   	   /** move constructor */
98   	   ObjTable(ObjTable&& o)
99   	       : scip_(o.scip_),
100  	         scip_name_(0),
101  	         scip_desc_(0),
102  	         scip_position_(o.scip_position_),
103  	         scip_earlieststage_(o.scip_earlieststage_)
104  	   {
105  	      std::swap(scip_name_, o.scip_name_);
106  	      std::swap(scip_desc_, o.scip_desc_);
107  	   }
108  	
109  	   /** destructor */
110  	   virtual ~ObjTable()
111  	   {
112  	      /* the macro SCIPfreeMemoryArray does not need the first argument: */
113  	      /*lint --e{64}*/
114  	      SCIPfreeMemoryArray(scip_, &scip_name_);
115  	      SCIPfreeMemoryArray(scip_, &scip_desc_);
116  	   }
117  	
118  	   /** assignment of polymorphic classes causes slicing and is therefore disabled. */
119  	   ObjTable& operator=(const ObjTable& o) = delete;
120  	
121  	   /** assignment of polymorphic classes causes slicing and is therefore disabled. */
122  	   ObjTable& operator=(ObjTable&& o) = delete;
123  	
124  	   /** destructor of statistics table to free user data (called when SCIP is exiting)
125  	    *
126  	    *  @see SCIP_DECL_TABLEFREE(x) in @ref type_disp.h
127  	    */
128  	   virtual SCIP_DECL_TABLEFREE(scip_free)
129  	   {  /*lint --e{715}*/
130  	      return SCIP_OKAY;
131  	   }
132  	
133  	   /** initialization method of statistics table (called after problem was transformed)
134  	    *
135  	    *  @see SCIP_DECL_TABLEINIT(x) in @ref type_table.h
136  	    */
137  	   virtual SCIP_DECL_TABLEINIT(scip_init)
138  	   {  /*lint --e{715}*/
139  	      return SCIP_OKAY;
140  	   }
141  	
142  	   /** deinitialization method of statistics table (called before transformed problem is freed)
143  	    *
144  	    *  @see SCIP_DECL_TABLEEXIT(x) in @ref type_table.h
145  	    */
146  	   virtual SCIP_DECL_TABLEEXIT(scip_exit)
147  	   {  /*lint --e{715}*/
148  	      return SCIP_OKAY;
149  	   }
150  	
151  	   /** solving process initialization method of statistics table (called when branch and bound process is about to begin)
152  	    *
153  	    *  @see SCIP_DECL_TABLEINITSOL(x) in @ref type_table.h
154  	    */
155  	   virtual SCIP_DECL_TABLEINITSOL(scip_initsol)
156  	   {  /*lint --e{715}*/
157  	      return SCIP_OKAY;
158  	   }
159  	
160  	   /** solving process deinitialization method of statistics table (called before branch and bound process data is freed)
161  	    *
162  	    *  @see SCIP_DECL_TABLEEXITSOL(x) in @ref type_table.h
163  	    */
164  	   virtual SCIP_DECL_TABLEEXITSOL(scip_exitsol)
165  	   {  /*lint --e{715}*/
166  	      return SCIP_OKAY;
167  	   }
168  	
169  	   /** output method of statistics table to output file stream 'file'
170  	    *
171  	    *  @see SCIP_DECL_TABLEOUTPUT(x) in @ref type_table.h
172  	    */
173  	   virtual SCIP_DECL_TABLEOUTPUT(scip_output) = 0;
174  	};
175  	
176  	} /* namespace scip */
177  	
178  	
179  	
180  	/** creates the statistics table for the given statistics table object and includes it in SCIP
181  	 *
182  	 *  The method should be called in one of the following ways:
183  	 *
184  	 *   1. The user is resposible of deleting the object:
185  	 *       SCIP_CALL( SCIPcreate(&scip) );
186  	 *       ...
187  	 *       MyTable* mytable = new MyTable(...);
188  	 *       SCIP_CALL( SCIPincludeObjTable(scip, &mytable, FALSE) );
189  	 *       ...
190  	 *       SCIP_CALL( SCIPfree(&scip) );
191  	 *       delete mytable;    // delete table AFTER SCIPfree() !
192  	 *
193  	 *   2. The object pointer is passed to SCIP and deleted by SCIP in the SCIPfree() call:
194  	 *       SCIP_CALL( SCIPcreate(&scip) );
195  	 *       ...
196  	 *       SCIP_CALL( SCIPincludeObjTable(scip, new MyTable(...), TRUE) );
197  	 *       ...
198  	 *       SCIP_CALL( SCIPfree(&scip) );  // destructor of MyTable is called here
199  	 */
200  	SCIP_EXPORT
201  	SCIP_RETCODE SCIPincludeObjTable(
202  	   SCIP*                 scip,               /**< SCIP data structure */
203  	   scip::ObjTable*       objtable,           /**< statistics table object */
204  	   SCIP_Bool             deleteobject        /**< should the statistics table object be deleted when statistics table is freed? */
205  	   );
206  	
207  	/** returns the statistics table object of the given name, or 0 if not existing */
208  	SCIP_EXPORT
209  	scip::ObjTable* SCIPfindObjTable(
210  	   SCIP*                 scip,               /**< SCIP data structure */
211  	   const char*           name                /**< name of statistics table */
212  	   );
213  	
214  	/** returns the statistics table object for the given statistics table */
215  	SCIP_EXPORT
216  	scip::ObjTable* SCIPgetObjTable(
217  	   SCIP*                 scip,               /**< SCIP data structure */
218  	   SCIP_TABLE*           table               /**< statistics table */
219  	   );
220  	
221  	#endif
222