rasdaman complete source
tile.hh
Go to the documentation of this file.
1 /*
2 * This file is part of rasdaman community.
3 *
4 * Rasdaman community is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation, either version 3 of the License, or
7 * (at your option) any later version.
8 *
9 * Rasdaman community is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with rasdaman community. If not, see <http://www.gnu.org/licenses/>.
16 *
17 * Copyright 2003, 2004, 2005, 2006, 2007, 2008, 2009 Peter Baumann /
18 rasdaman GmbH.
19 *
20 * For more information please see <http://www.rasdaman.org>
21 * or contact Peter Baumann via <baumann@rasdaman.com>.
22 */
23 
24 /*************************************************************
25  *
26  *
27  * PURPOSE:
28  * Tile is the abstract base class for persTile, transTile
29  * and constTile
30  *
31  *
32  * COMMENTS:
33  *
34  ************************************************************/
35 
36 #ifndef _TILE_HH_
37 #define _TILE_HH_
38 
39 #include <vector>
40 #include <set>
41 
42 #include "raslib/minterval.hh" // for r_Minterval
43 #include "raslib/point.hh" // for r_Point
44 #include "raslib/mddtypes.hh" // for r_Data_Format
45 #include "catalogmgr/ops.hh" // for Ops::OpType
46 #include "relcatalogif/basetype.hh" // for BaseType
47 #include "relblobif/tileid.hh"
48 #include "relblobif/dbtile.hh"
49 #include "reladminif/dbref.hh"
50 
51 #ifdef RMANBENCHMARK
52 #include "raslib/rmdebug.hh" // for RMTimer
53 #endif
54 class KeyObject;
55 class PersMDDObjIx;
56 
57 
58 //@ManMemo: Module: {\bf cachetamgr}.
59 
60 /*@Doc:
61 
62 {\bf Interdependencies}
63 
64 Tile uses a pointer to \Ref{BaseType} to store the base type of the Tile.
65 It uses a \Ref{r_Minterval} to store the domain of the Tile.
66 Pointers to Tiles are used by many classes.
67 
68 Persistent Tiles are created either by servercomm, when data is received from a client, or by indexif if a BLOBTile is retrieved from the
69 index. The query tree can also create tiles in case of INSERT or UPDATE queries, and Tile::splitTile creates new tiles.
70 */
71 
80 class Tile
81 {
82 public:
83 
85  const Tile& operator=(const Tile& cell);
86 
87  Tile(const r_Minterval& newDom, const BaseType* newType, DBTileId newBLOBTile);
88  /*Doc
89  Constructs a new Tile with basetype {\tt newType} and spatial
90  domain {\tt newDom}. Its contents are stored in \Ref{BLOBTile}
91  {\tt newBLOBTile}. The contents are potentially compressed.
92  */
93  Tile(const Tile& tile);
95  Tile(std::vector<Tile*>* tilesVec);
96  /*@Doc:
97  Constructs a new Tile out of the vector {\tt tilesVec}
98  containing pointers to tiles. The Tile created has the
99  closure of the domains of all tiles in the vector as it's domain
100  and the same base type. The tiles should not overlap and must have
101  the same basetype and dimension. Non filled areas in the created
102  tile are of undefined value. The contents are copied, the memory
103  of the tiles and the vector has to be freed by the caller. The
104  resulting Tile is by default uncompressed.
105  */
106  /*@ManMemo:
107  constructs a Tile with the domain {\tt resDom}
108  and the contents joined out of the Tiles in {\tt tilesVec}.
109  */
110  Tile(std::vector<Tile*>* tilesVec, const r_Minterval& resDom);
111  /*@Doc:
112  Constructs a new Tile out of the vector {\tt tilesVec}
113  containing pointers to tiles. The contents which fall in the area
114  {\tt resDom} are copied into the new Tile. The Tile
115  created has the domain {\tt resDom} and the same base type as the
116  Tiles in {\tt tilesVec}. The tiles should not overlap and must
117  have the same basetype and dimension. Non filled areas in the
118  created tile are of undefined value. The memory of the tiles and
119  the vector has to be freed by the caller. Every tile in {\tt
120  tilesVec} has to overlap with {\tt resDom}.
121  */
123  Tile(const Tile* projTile, const r_Minterval& projDom, const std::set<r_Dimension, std::less<r_Dimension> >* projDim);
124  /*@Doc:
125  Constructs a new Tile out of the projection of Tile {\tt
126  projTile} with the dimensions given in {\tt projDim} projected
127  away (zero based dimension counting!). Only the area specified in
128  projDom is used for the new Tile. {\tt projDom} must have the
129  same dimension as the domain of {\tt projTile}. Dimensions
130  projected away must have the coordinate to be projected at
131  as domain, e.g. 28:28.
132  */
133  /*@ManMemo: constructs a Tile with base type {\tt newType} and
134  spatial domain {\tt newDom}. */
135  Tile(const r_Minterval& newDom, const BaseType* newType, r_Data_Format newFormat = r_Array);
136  /*@Doc
137  The contents are undefined! This constructor should usually not
138  be used.
139  */
141  Tile(const r_Minterval& newDom, const BaseType* newType, char* newCells, r_Bytes newSize = 0, r_Data_Format newFormat = r_Array);
142  /*Doc
143  Constructs a new Tile with basetype {\tt newType} and spatial
144  domain {\tt newDom}. The char array {\tt newCells} contains the
145  potentially compressed contents of the new Tile. The memory for
146  the cells is managed by Tile and has to be allocated with
147  malloc(). If newSize is 0, it is assumed to be uncompressed contents,
148  and the size is calculated from domain and base type.
149  */
150  Tile(const r_Minterval& newDom, const BaseType* newType, const char* newCells, bool, r_Bytes newSize = 0, r_Data_Format newFormat = r_Array);
151  /*Doc
152  Constructs a new Tile with basetype {\tt newType} and spatial
153  domain {\tt newDom}. The char array {\tt newCells} contains the
154  potentially compressed contents of the new Tile. 'bool' is used only,
155  for making the difference between this constructor and the upper one.
156  This one doesn't delete the passed data!
157  If newSize is 0, it is assumed to be uncompressed contents,
158  and the size is calculated from domain and base type.
159  */
160  //@Man: read methods
162  const r_Minterval& getDomain() const;
165  const BaseType* getType() const;
167  r_Dimension getDimension() const;
169  r_Bytes getSize() const;
171  r_Bytes getCompressedSize() const;
173  r_Data_Format getDataFormat() const;
175  bool isPersistent() const;
177  bool isCompressed() const;
179 
180  //@Man: functions to reading and writing the content.
182  const char* getCell(r_Area index) const;
185  char* getCell(r_Area index);
187  void setCell(r_Area index, const char* newCell);
189  char* getCell(const r_Point& aPoint);
191  const char* getCell(const r_Point& aPoint) const;
193  const char* getContents() const;
195  char* getContents();
197  void setContents(char* newContents);
198  /*@Doc:
199  The memory for the cells is managed by the Tile and has to be
200  allocated with malloc(). Its size has to be correct according to
201  domain and base type of the Tile.
202  */
204 
206  void printStatus(unsigned int level = 0, std::ostream &stream = std::cout) const;
207  /*@Doc:
208  Prints the contents of the Tile on stream. Prints every cell in
209  the Tile with the {\tt printCell} function of the \Ref{BaseType}.
210  For dimensionality > 1, 2D-slices are printed with an empty line
211  in between. These 2D slices cover the lowest 2 indices (0 and 1).
212  */
213 
214  void setPersistent(bool state = true);
215 
217  std::vector<Tile*>* splitTile(r_Minterval resDom, int storageDomain = 0);
218  /*@Doc:
219  The Tile is split into subtiles with the same extent as {\tt
220  resDom}. The storage domain (pers. or transient) of the subtiles is
221  defined by {\tt storageDomain}. If it is null (default value) they
222  have the same type (\Ref{TransTile} resp. \Ref{Tile}) as self.
223  If {\tt storageDomain} is 1, they are persistent, if {\tt storageDomain}
224  has a value other than 0 or 1, they are made transient.
225  The algoritm starts with the smallest
226  coordinate in each dimension, so that if the Tile does not divide
227  into Tiles of extent {\tt resDom}, the last Tiles in each
228  dimension may be smaller. The Tiles returned as pointers have to
229  be freed by the caller!
230  */
231 
232 
233  //@Man: methods for carrying out operations
235  char* execCondenseOp(CondenseOp* myOp, const r_Minterval& areaOp);
237  /*@Doc:
238  The condense function {\tt myOp} is applied to all cells of self in
239  the area {\tt areaOp}. The result is stored in myOp which also
240  gives the start value for the condense operation. The return value
241  is a pointer to a member of myOp, so it gets invalid if myOp is
242  deleted! For further information on condense operations see \Ref{Ops}.
243  */
244 
245 
247  void execUnaryOp(UnaryOp* myOp, const r_Minterval& areaRes, const Tile* opTile, const r_Minterval& areaOp);
248  /*@Doc:
249  The unary function {\tt myOp} is applied to all cells of the tile
250  {\tt opTile} in the area {\tt areaOp}. The result of the
251  operation is stored in self in the area {\tt areaRes}. The areas
252  must have the same extent, but may differ in an offset.
253  */
254 
256  void execBinaryOp( BinaryOp* myOp, const r_Minterval& areaRes,
257  const Tile* op1Tile, const r_Minterval& areaOp1,
258  const Tile* op2Tile, const r_Minterval& areaOp2);
259  /*@Doc:
260  The binary function {\tt myOp} is applied to all cells of the tiles
261  {\tt op1Tile} and {\tt op2Tile} in the respective areas. The
262  result of the operation is stored in self in the area {\tt
263  areaRes}. The areas must have the same extent for all tiles. but
264  may differ in an offset vector.
265  */
266 
268  virtual void execConstOp( BinaryOp* myOp, const r_Minterval& areaRes,
269  const Tile* opTile, const r_Minterval& areaOp,
270  const char* cell, int constPos = 1);
271  /*@Doc:
272  The binary function {\tt op} is applied to all cells of the tile
273  {\tt op1Tile} and the constant {\tt cell} in the area {\tt
274  areaOp}. If {\tt constPos} is 1, then {\tt const op cell} is
275  carried out; if it is 2, then {\tt cell op const} is carried out.
276  The result of the operations is stored in self in the area {\tt
277  areaRes}. {\tt areaOp} and {\tt areaRes} must have the same
278  extent, but may differ in an offset.
279  */
280 
281 
283  virtual void execMarrayOp(MarrayOp* myOp, const r_Minterval& areaRes, const r_Minterval& areaOp);
284  /*@Doc:
285  {\tt myOp} maps a point to a value. It is important that the base
286  type specified it the same as the tile has.
287  */
288 
290  static char* execGenCondenseOp(GenCondenseOp* myOp, const r_Minterval& areaOp);
291  /*@Doc:
292  {\tt myOp} maps a point to a value. The return values has the resType
293  defined in {\tt myOp}. The tile is not accessed (static function),
294  the function is defined here to be located together with the other
295  operation execution functions.
296  */
298  virtual void execScaleOp( const Tile* opTile, const r_Minterval& areaOp,
299  const r_Point& origin,
300  const std::vector<double>& scaleFactors);
301  /*@Doc:
302  The tile {\tt opTile} is scaled down in each dimension by the
303  corresponding element in vector {\tt scaleFactors}. The result
304  is stored in the tile on which the operation is called. Scaling
305  is done by using a nearest neighbour algorithm based on
306  {\tt origin} as the point where the scaling process started.
307  {\tt opTile} has to have the same dimensionality as the result
308  tile and scaleFactors has to have a corresponding number of
309  elements.
310  */
312  int scaleGetDomain( const r_Minterval& areaOp,
316  const std::vector<double>& scaleFactors,
317  r_Minterval& areaScaled);
318 
319  /*@Doc:
320  Return result domain in areaScaled if scaling using the factors in
321  scaleFactors would be applied in area {\tt areaOp} with the scaling
322  factors specified in {\tt scaleFactors}. If the tile would become
323  completely empty, false is returned. This can then be used to create
324  a temporary tile for the result on which the {\tt execScaleOp}
325  function can be called.
326  */
327 
329  virtual ~Tile();
330 
332  virtual void copyTile(const r_Minterval& areaRes, const Tile *opTile, const r_Minterval& areaOp);
333  /*@Doc:
334  The part of opTile covered by areaOp is copied to areaRes of this tile. Identical in functionality to execUnaryOp(OP_IDENTITY, ...) but much faster.
335  Requires matching base types and matching domains.
336  */
337 
339  /*Doc
340  Returns a pointer to the \Ref{BLOBTile} holding the contents of
341  the Tile. This function is used to persistently store the
342  contents of a Tile.
343  */
344 
345 #ifdef RMANBENCHMARK
346  // RMTimer for taking O2 times. Could be protected. Is controlled
347  // in servercomm/servercomm2.cc.
348  static RMTimer opTimer;
349  static RMTimer relTimer;
350 #endif
351 
352 protected:
353  //@Man: utility functions used internally.
355  r_Bytes calcOffset(const r_Point& point) const;
357  // fill cells of size size with pattern newCell of size patSize.
359 
361  r_Minterval domain;
363  const BaseType* type;
366 };
367 
368 #endif
bool isCompressed() const
returns true if the contents are currently compressed and must be decompressed in order to be usefull...
void printStatus(unsigned int level=0, std::ostream &stream=std::cout) const
printed output for testing.
const Tile & operator=(const Tile &cell)
assignment operator (needed, as class uses dynamic memory).
const BaseType * getType() const
returns the BaseType of the tile.
r_Bytes getCompressedSize() const
returns size of the contents of the tile as stored in chars.
void execBinaryOp(BinaryOp *myOp, const r_Minterval &areaRes, const Tile *op1Tile, const r_Minterval &areaOp1, const Tile *op2Tile, const r_Minterval &areaOp2)
carries out binary function with self as result.
bool isPersistent() const
returns true for persistent instances.
int scaleGetDomain(const r_Minterval &areaOp, const std::vector< double > &scaleFactors, r_Minterval &areaScaled)
Definition: keyobject.hh:43
virtual void copyTile(const r_Minterval &areaRes, const Tile *opTile, const r_Minterval &areaOp)
copy a subcube from one tile to another
char * execCondenseOp(CondenseOp *myOp, const r_Minterval &areaOp)
carries out condense function (const)
static char * execGenCondenseOp(GenCondenseOp *myOp, const r_Minterval &areaOp)
executes general condense operation { myOp} in area { areaOp} (const)
virtual void execMarrayOp(MarrayOp *myOp, const r_Minterval &areaRes, const r_Minterval &areaOp)
fills tile in area { areaRes} using MarrayOp { myOp}.
virtual void execScaleOp(const Tile *opTile, const r_Minterval &areaOp, const r_Point &origin, const std::vector< double > &scaleFactors)
executes scaling operation.
const BaseType * type
pointer to base type for cells of Tile.
Definition: tile.hh:363
void execUnaryOp(UnaryOp *myOp, const r_Minterval &areaRes, const Tile *opTile, const r_Minterval &areaOp)
carries out unary function with self as result.
virtual void execConstOp(BinaryOp *myOp, const r_Minterval &areaRes, const Tile *opTile, const r_Minterval &areaOp, const char *cell, int constPos=1)
carries out binary function with self as result.
const r_Minterval & getDomain() const
returns the spatial domain of the tile.
r_Bytes getSize() const
returns size of the (uncompressed) contents of the tile in chars.
r_Bytes calcOffset(const r_Point &point) const
calculate offset in cells
virtual ~Tile()
virtual destructor.
const char * getContents() const
returns pointer to (uncompressed) contents of Tile.
DBTileId getDBTile()
Definition: tile.hh:80
Definition: relcatalogif/basetype.hh:66
const char * getCell(r_Area index) const
access to cell for reading (index is 1D) one cell length is basetype length.
void setPersistent(bool state=true)
Tile(const r_Minterval &newDom, const BaseType *newType, DBTileId newBLOBTile)
Module: { raslib}.
Definition: rmdebug.hh:298
r_Data_Format getDataFormat() const
returns the format of the data maintained by the tile
r_Minterval domain
spatial domain of the tile.
Definition: tile.hh:361
DBTileId blobTile
Smart pointer to the persistent BLOBTile.
Definition: tile.hh:365
void setContents(char *newContents)
sets (uncompressed) contents of Tile.
std::vector< Tile * > * splitTile(r_Minterval resDom, int storageDomain=0)
splits tile in vector of tiles of smaller size.
r_Dimension getDimension() const
returns the dimension of the tile.
void setCell(r_Area index, const char *newCell)
set cell (index is 1D).