source: branches/dev/Common/IpJournalist.hpp @ 567

Last change on this file since 567 was 567, checked in by andreasw, 15 years ago

adapted for Portland compilers

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 12.0 KB
Line 
1// Copyright (C) 2004, 2005 International Business Machines and others.
2// All Rights Reserved.
3// This code is published under the Common Public License.
4//
5// $Id: IpJournalist.hpp 567 2005-11-01 23:27:11Z andreasw $
6//
7// Authors:  Carl Laird, Andreas Waechter     IBM    2004-08-13
8
9#ifndef __IPJOURNALIST_HPP__
10#define __IPJOURNALIST_HPP__
11
12#include <string>
13#include <vector>
14#include "IpTypes.hpp"
15#include "IpReferenced.hpp"
16#include "IpSmartPtr.hpp"
17
18#ifdef HAVE_CSTDARG
19# include <cstdarg>
20#else
21# ifdef HAVE_STDARG_H
22#  include <stdarg.h>
23# else
24#  error "don't have header file for stdarg"
25# endif
26#endif
27
28#ifdef HAVE_CSTDIO
29# include <cstdio>
30#else
31# ifdef HAVE_STDIO_H
32#  include <stdio.h>
33# else
34#  error "don't have header file for stdio"
35# endif
36#endif
37
38namespace Ipopt
39{
40
41  // forward declarations
42  class Journal;
43  class FileJournal;
44
45  /**@name Journalist Enumerations. */
46  //@{
47  /** Print Level Enum. */
48  enum EJournalLevel {
49    J_INSUPPRESSIBLE=-1,
50    J_NONE=0,
51    J_ERROR,
52    J_WARNING,
53    J_SUMMARY,
54    J_ITERSUMMARY,
55    J_DETAILED,
56    J_MOREDETAILED,
57    J_VECTOR,
58    J_MOREVECTOR,
59    J_MATRIX,
60    J_MOREMATRIX,
61    J_ALL,
62    J_LAST_LEVEL
63  };
64
65  /** Category Selection Enum. */
66  enum EJournalCategory {
67    J_DBG=0,
68    J_STATISTICS,
69    J_MAIN,
70    J_INITIALIZATION,
71    J_BARRIER_UPDATE,
72    J_SOLVE_PD_SYSTEM,
73    J_FRAC_TO_BOUND,
74    J_LINEAR_ALGEBRA,
75    J_LINE_SEARCH,
76    J_SOLUTION,
77    J_DOCUMENTATION,
78    J_NLP,
79    J_TIMING_STATISTICS,
80    J_LAST_CATEGORY
81  };
82  //@}
83
84  /** Class responsible for all message output.
85   * This class is responsible for all messaging and output.
86   * The "printing" code or "author" should send ALL messages to the
87   * Journalist, indicating an appropriate category and print level.
88   * The journalist then decides, based on reader specified
89   * acceptance criteria, which message is actually printed in which
90   * journals.
91   * This allows the printing code to send everything, while the
92   * "reader" can decide what they really want to see.
93   *
94   * Authors:
95   * Authors use the
96   * Journals: You can add as many Journals as you like to the
97   * Journalist with the AddJournal or the AddFileJournal methods.
98   * Each one represents a different printing location (or file). 
99   * Then, you can call the "print" methods of the Journalist to output
100   * information to each of the journals.
101   *
102   * Acceptance Criteria: Each print message should be flagged
103   * appropriately with an EJournalCategory and EJournalLevel.
104   *
105   * The AddFileJournal
106   * method returns a pointer to the newly created Journal object
107   * (if successful) so you can set Acceptance criteria for that
108   * particular location.
109   *
110   */
111  class Journalist : public ReferencedObject
112  {
113  public:
114    /**@name Constructor / Desructor. */
115    //@{
116    /** Constructor. */
117    Journalist();
118
119    /** Destructor... */
120    virtual ~Journalist();
121    //@}
122
123    /**@name Author Methods.
124     * These methods are used by authoring code, or code that wants
125     * to report some information.
126     */
127    //@{
128    /** Method to print a formatted string */
129    void Printf(EJournalLevel level, EJournalCategory category,
130                const char* format, ...) const;
131
132    /** Method to print a long string including indentation.  The
133     *  string is printed starting at the current position.  If the
134     *  position (counting started at the current position) exceeds
135     *  max_length, a new line is inserted, and indent_spaces many
136     *  spaces are printed before the string is continued.  This is
137     *  for example used during the printing of the option
138     *  documentation. */
139    void PrintStringOverLines(EJournalLevel level, EJournalCategory category,
140                              Index indent_spaces, Index max_length,
141                              const std::string& line) const;
142
143    /** Method to print a formatted string with indentation */
144    void PrintfIndented(EJournalLevel level,
145                        EJournalCategory category,
146                        Index indent_level,
147                        const char* format, ...) const;
148
149    /** Method to print a formatted string
150     * using the va_list argument. */
151    void VPrintf(EJournalLevel level,
152                 EJournalCategory category,
153                 const char* pformat,
154                 va_list ap) const;
155
156    /** Method to print a formatted string with indentation,
157     * using the va_list argument. */
158    void VPrintfIndented(EJournalLevel level,
159                         EJournalCategory category,
160                         Index indent_level,
161                         const char* pformat,
162                         va_list ap) const;
163
164    /** Method that returns true if there is a Journal that would
165     *  write output for the given JournalLevel and JournalCategory.
166     *  This is useful if expensive computation would be required for
167     *  a particular output.  The author code can check with this
168     *  method if the computations are indeed required.
169     */
170    bool ProduceOutput(EJournalLevel level,
171                       EJournalCategory category) const;
172
173
174    /** Method that flushes the current buffer for all Journalists.
175     Calling this method after one optimization run helps to avoid
176     cluttering output with that produced by other parts of the
177     program (e.g. written in Fortran) */
178    void FlushBuffer() const;
179    //@}
180
181    /**@name Reader Methods.
182     * These methods are used by the reader. The reader will setup the
183     * journalist with each output file and the acceptance
184     * criteria for that file.
185     *
186     * Use these methods to setup the journals (files or other output).
187     * These are the internal objects that keep track of the print levels
188     * for each category. Then use the internal Journal objects to
189     * set specific print levels for each category (or keep defaults).
190     * 
191     */
192    //@{
193    /** Add a new journal.  The location_name is a string identifier,
194     *  which can be used to obtain the pointer to the new Journal at
195     *  a later point using the GetJournal method.
196     *  The default_level is
197     *  used to initialize the * printing level for all categories.
198     */
199    bool AddJournal(const SmartPtr<Journal> jrnl);
200
201    /** Add a new FileJournal. fname is the name
202     *  of the * file to which this Journal corresponds.  Use
203     *  fname="stdout" * for stdout, and use fname="stderr" for
204     *  stderr.  This method * returns the Journal pointer so you can
205     *  set specific acceptance criteria.  It returns NULL if there
206     *  was a problem creating a new Journal.   
207     */
208    SmartPtr<Journal> AddFileJournal(
209      const std::string& location_name,    /** identifier */
210      const std::string& fname,
211      EJournalLevel default_level = J_WARNING
212    );
213
214    /** Get an existing journal.  You can use this method to change
215     *  the acceptance criteria at runtime.
216     */
217    SmartPtr<Journal> GetJournal(const std::string& location_name);
218    //@}
219
220  private:
221    /**@name Default Compiler Generated Methods
222     * (Hidden to avoid implicit creation/calling).
223     * These methods are not implemented and
224     * we do not want the compiler to implement
225     * them for us, so we declare them private
226     * and do not define them. This ensures that
227     * they will not be implicitly created/called. */
228    //@{
229    /** Copy Constructor */
230    Journalist(const Journalist&);
231
232    /** Overloaded Equals Operator */
233    void operator=(const Journalist&);
234    //@}
235
236    //** Private Data Members. */
237    //@{
238    std::vector< SmartPtr<Journal> > journals_;
239    //@}
240  };
241
242  /** Journal class (part of the Journalist implementation.). This
243   *  class is the base class for all Journals. It controls the
244   *  acceptance criteria for print statements etc. Derived classes
245   *  like the FileJournal - output those messages to specific locations
246   */
247  class Journal : public ReferencedObject
248  {
249  public:
250    /** Constructor. */
251    Journal(const std::string& name, EJournalLevel default_level);
252
253    /** Destructor. */
254    virtual ~Journal();
255
256    /** Get the name of the Journal */
257    std::string Name();
258
259    /** Set the print level for a particular category. */
260    void SetPrintLevel(
261      EJournalCategory category, EJournalLevel level
262    );
263
264    /** Set the print level for all category. */
265    void SetAllPrintLevels(
266      EJournalLevel level
267    );
268
269    /**@name Journal Output Methods. These methods are called by the
270     *  Journalist who first checks if the output print level and category
271     *  are acceptable.
272     *  Calling the Print methods explicitly (instead of through the
273     *  Journalist will output the message regardless of print level
274     *  and category. You should use the Journalist to print & flush instead
275     */
276    //@{
277    /** Ask if a particular print level/category is accepted by the
278     * journal.
279     */
280    bool IsAccepted(
281      EJournalCategory category, EJournalLevel level
282    ) const;
283
284    /** Print to the designated output location */
285    void Print(const char* str)
286    {
287      PrintImpl(str);
288    }
289
290    /** Printf to the designated output location */
291    void Printf(const char* pformat, va_list ap)
292    {
293      PrintfImpl(pformat, ap);
294    }
295
296    /** Flush output buffer.*/
297    void FlushBuffer()
298    {
299      FlushBufferImpl();
300    }
301    //@}
302
303  protected:
304    /**@name Implementation version of Print methods. Derived classes
305     * should overload the Impl methods.
306     */
307    //@{
308    /** Print to the designated output location */
309    virtual void PrintImpl(const char* str)=0;
310
311    /** Printf to the designated output location */
312    virtual void PrintfImpl(const char* pformat, va_list ap)=0;
313
314    /** Flush output buffer.*/
315    virtual void FlushBufferImpl()=0;
316    //@}
317
318  private:
319    /**@name Default Compiler Generated Methods
320     * (Hidden to avoid implicit creation/calling).
321     * These methods are not implemented and
322     * we do not want the compiler to implement
323     * them for us, so we declare them private
324     * and do not define them. This ensures that
325     * they will not be implicitly created/called. */
326    //@{
327    /** Default Constructor */
328    Journal();
329
330    /** Copy Constructor */
331    Journal(const Journal&);
332
333    /** Overloaded Equals Operator */
334    void operator=(const Journal&);
335    //@}
336
337    /** Name of the output location */
338    std::string name_;
339
340    /** vector of integers indicating the level for each category */
341    Index print_levels_[J_LAST_CATEGORY];
342  };
343
344
345  /** FileJournal class. This is a particular Journal implementation that
346   *  writes to a file for output. It can write to (stdout, stderr, or disk)
347   *  by using "stdout" and "stderr" as filenames.
348   */
349  class FileJournal : public Journal
350  {
351  public:
352    /** Constructor. */
353    FileJournal(const std::string& name, EJournalLevel default_level);
354
355    /** Destructor. */
356    virtual ~FileJournal();
357
358    /** Open a new file for the output location.
359     *  Special Names: stdout means stdout,
360     *               : stderr means stderr.
361     *
362     *  Return code is false only if the file with the given name
363     *  could not be opened.
364     */
365    bool Open(const char* fname);
366
367  protected:
368    /**@name Implementation version of Print methods - Overloaded from
369     * Journal base class.
370     */
371    //@{
372    /** Print to the designated output location */
373    virtual void PrintImpl(const char* str);
374
375    /** Printf to the designated output location */
376    virtual void PrintfImpl(const char* pformat, va_list ap);
377
378    /** Flush output buffer.*/
379    virtual void FlushBufferImpl();
380    //@}
381
382  private:
383    /**@name Default Compiler Generated Methods
384     * (Hidden to avoid implicit creation/calling).
385     * These methods are not implemented and
386     * we do not want the compiler to implement
387     * them for us, so we declare them private
388     * and do not define them. This ensures that
389     * they will not be implicitly created/called. */
390    //@{
391    /** Default Constructor */
392    FileJournal();
393
394    /** Copy Constructor */
395    FileJournal(const FileJournal&);
396
397    /** Overloaded Equals Operator */
398    void operator=(const FileJournal&);
399    //@}
400
401    /** FILE pointer for the output destination */
402    FILE* file_;
403  };
404}
405
406#endif
Note: See TracBrowser for help on using the repository browser.