casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Memory.h
Go to the documentation of this file.
1 //# Memory.h: Memory related information and utilities.
2 //# Copyright (C) 1997,2001
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //#
27 //# $Id$
28 
29 #ifndef CASA_MEMORY_H
30 #define CASA_MEMORY_H
31 
32 #include <casacore/casa/aips.h>
33 //# The following is used to get size_t.
34 #include <casacore/casa/stdlib.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 // <summary>Memory related information and utilities.</summary>
39 
40 // use visibility=export>
41 
42 // <reviewed reviewer="rmarson" date="1997/11/12" tests="tMemory" demos="">
43 // </reviewed>
44 
45 // <prerequisite>
46 // <li> General knowledge of C/C++ memory allocation issues.
47 // </prerequisite>
48 //
49 // <synopsis>
50 // This class should generally not be used by general application programmers.
51 // Instead you should use the memory information available in the
52 // <linkto class=AppInfo>AppInfo</linkto> class.
53 //
54 // This class reports on the dynamic ("heap") memory used by this process, and
55 // it can attempt to release some of that memory back to the operating
56 // system. The class reports on <src>allocated</src> memory, which is memory
57 // that the process has actually requested, typically via <src>new</src>, but
58 // also via <src>malloc</src>. The number might be somewhat larger than actually
59 // requested by the programmer to account for overhead and alignment
60 // considerations. The class also reports <src>assigned</src> memory, which is
61 // the total memory that the process has been given, not all of which has been
62 // allocated by the programmer. Typically this results from memory which has
63 // been <src>delete</src>d by the programmer, but has not been released to the
64 // OS on the assumption that it might be needed again. (Getting and releasing
65 // memory to the OS can be expensive).
66 //
67 // At present, the values for allocated and assigned memory are obtained via the
68 // <src>mallinfo()</src> call, usually defined in <src>malloc.h</src>. This call
69 // seems to be adequately portable for Unix. Another alternative would be to
70 // replace global operators <src>new</src> and <src>delete</src> for systems
71 // that do not have <src>mallinfo()</src>.
72 //
73 // The member function <src>releaseMemory()</src> on some system will attempt
74 // to return assigned but unallocated memory to the OS. If the compilation
75 // system cannot automatically determine how to do this (at present it only
76 // recognizes Linux systems), you can you this function by setting the
77 // preprocessor symbol <src>AIPS_RELEASEMEM</src> to a C++ statement which
78 // will release memory to the OS. For example, if you are using GNU malloc
79 // you could set it to <src>malloc_trim(0)</src>. Note that
80 // <src>releaseMemory()</src> might be a no-op on many systems, and that
81 // calling it might be expensive so it should not be called in tight-loops.
82 //
83 // Note that this class does not use any Casacore facilities and does not cause
84 // any Casacore code to be linked in to your executable.
85 // </synopsis>
86 //
87 // <example>
88 // We could attempt to return memory to the OS when we are wasting a lot
89 // of memory as follows.
90 // <srcBlock>
91 // if (Memory::assignedMemoryInBytes() - Memory::allocatedMemoryInBytes() >
92 // 1024*1024) {
93 // Memory::releaseMemory(); // Attempt to release if more than 1M "wasted"
94 // }
95 // </srcBlock>
96 // </example>
97 //
98 // <motivation>
99 // At run time we need to be able to make decisions about whether we should
100 // keep things in memory or about whether we should do I/O (e.g. use an
101 // Array or a PagedArray).
102 // </motivation>
103 //
104 // <todo asof="1997/11/10">
105 // <li> We might some day want to put actual allocation/deallocation
106 // functions in here if the mallinfo() interface turns out to not
107 // be portable.
108 // </todo>
109 
110 class Memory
111 {
112 public:
113  // How much memory has been allocated by the programmer (via either
114  // <src>new</src> or <src>malloc</src>. This can include some extra
115  // overhead bytes, e.g. for alignment reasons.
116  static size_t allocatedMemoryInBytes();
117  // How much memory in in the memory "pool" of this process. This includes
118  // not only the allocated memory, but some memory which has been
119  // <src>delete</src>d but not returned to the OS on the assumption that
120  // it might be needed again.
121  static size_t assignedMemoryInBytes();
122  // Attempt to release memory which has been assigned but not allocated.
123  // On many systems this will be a no-op, and even on systems in which it
124  // does something the amount of reclaimed memory cannot be specified.
125  // Since this function may be somewhat expensive to call it should not
126  // be called too often.
127  static void releaseMemory();
128 
129  // setMemoryOptions and setMemoryOption are typically front ends for mallopt
130  // which lets the user control some memory allocation parameters. setMemoryOptions
131  // is intended to be called only once at the start of a program while setMemoryOption
132  // could be called where desired (but see mallopt man page for possible side effects).
133  // Note: these two functions were added to address in a general way a memory
134  // fragmentation problem encountered on by the MIPSpro C++ compiler on the SGI.
135  static void setMemoryOptions();
136  static int setMemoryOption(int, int);
137 };
138 
139 
140 } //# NAMESPACE CASACORE - END
141 
142 #endif
143 
144 
static void setMemoryOptions()
setMemoryOptions and setMemoryOption are typically front ends for mallopt which lets the user control...
Memory related information and utilities. use visibility=export&gt;
Definition: Memory.h:110
static size_t assignedMemoryInBytes()
How much memory in in the memory &quot;pool&quot; of this process.
static void releaseMemory()
Attempt to release memory which has been assigned but not allocated.
static size_t allocatedMemoryInBytes()
How much memory has been allocated by the programmer (via either new or malloc.
static int setMemoryOption(int, int)
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42