MeVisLab Toolbox Reference
mlTileRequest.h
Go to the documentation of this file.
1 /*************************************************************************************
2 **
3 ** Copyright 2009, MeVis Medical Solutions AG
4 **
5 ** The user may use this file in accordance with the license agreement provided with
6 ** the Software or, alternatively, in accordance with the terms contained in a
7 ** written agreement between the user and MeVis Medical Solutions AG.
8 **
9 ** For further information use the contact form at https://www.mevislab.de/contact
10 **
11 **************************************************************************************/
12 
13 #ifndef ML_TILE_REQUEST_H
14 #define ML_TILE_REQUEST_H
15 
17 
18 // ML-includes
19 #include "mlInitSystemML.h"
20 
21 #include "mlSubImage.h"
22 #include "mlPagedImage.h"
23 #include "mlPageIDIterator.h"
24 
25 #include <set>
26 
27 ML_START_NAMESPACE
28 
29 class TileRequest;
30 class PageRequest;
31 class PageRequestQueueInterface;
32 
34 typedef void TileRequestFinishedCB(void* data, TileRequest* request);
35 
36 //-------------------------------------------------------------------------------------------
48 //-------------------------------------------------------------------------------------------
49 class ML_UNIX_ONLY_EXPORT(MLEXPORT) TileRequest
50 {
51 
52 public:
54  static TileRequest* allocate();
55 
57  static void deallocate(TileRequest* request);
58 
60  static void clearFreeList();
61 
62 private:
63  TileRequest();
64 
66  void cleanup();
67 
69  TileRequest* _freeListNext;
70 
72  static TileRequest* _freeListHead;
74  static Mutex _freeListMutex;
75 
76 public:
77 
82  void init(PagedImage* inputImage, const SubImageBox& box, MLDataType dataType,
83  const ScaleShiftData& scaleShift, bool readOnlyInputTile = false, bool tryToBecomeMemoryImage = false);
84 
87  UseMemoryManager = 0, //<! This will allocate the memory using the MemoryManager
88  UseMLAlloc = 1, //<! This will allocate the memory using MLAlloc
89  NoAllocation = 2, //<! This can be used if no data should be allocated at all (e.g., for processAllPages)
90  ExternalBuffer = 3 //<! This can be used to provide the data by the user (and to avoid freeing the data when something goes wrong)
91  };
92 
93  //------------------------------------------------------
96  //------------------------------------------------------
97 
102 
105 
109  void setNeededBy(PageRequest* request) {
110  _neededByPageRequest = request;
111  }
112 
116 
121 
123 
124  //------------------------------------------------------
127  //------------------------------------------------------
128 
132  void setAllocationPolicy(AllocationPolicy policy) { _allocationPolicy = policy; }
133 
135  AllocationPolicy getAllocationPolicy() const { return _allocationPolicy; }
136 
138  void allocateData();
139 
141  void forgetData() { _subImage.setData(nullptr); }
142 
144  void freeData() { if (_allocationPolicy!=ExternalBuffer) { _subImage.free(); } }
145 
147  const SubImage& getSubImage() const { return _subImage; }
148 
151  void setExternalDataBuffer(void* data) {
152  setAllocationPolicy(TileRequest::ExternalBuffer);
153  _subImage.setData(data);
154  }
155 
157  void setUseTileReadOnly(bool flag) { _readOnlyInputTile = flag; }
158 
160 
161  //------------------------------------------------------
164  //------------------------------------------------------
165 
167  bool hasFinished() const;
168 
171  _finishedCB = cb;
172  _finishedCBData = data;
173  }
174 
177  _internalFinishedCB = cb;
178  _internalFinishedCBData = data;
179  }
180 
182  double getProgress() const;
183 
185 
186  //------------------------------------------------------
189  //------------------------------------------------------
190 
192  bool hasError() const { return _error!=ML_RESULT_OK; }
193 
195  void setError(MLErrorCode error);
196 
198  MLErrorCode getError() const { return _error; }
199 
203 
208 
210  void collectPageRequestsWithErrors(std::set<PageRequest*>& result);
211 
213 
214  //------------------------------------------------------
217  //------------------------------------------------------
218 
221 
223  int getProcessingScope() const { return _processingScope; }
224 
226  void setProcessingScope(int scope) { _processingScope = scope; }
227 
229  const SubImageBox& getBox() const { return _subImage.getBox(); }
230 
232  bool intersectsPagedImage() const;
233 
236 
238 
239 protected:
241  friend class PageRequestCursor;
242 
250 
253  bool copyDataFromSubImg(SubImage& pageImage);
254 
257 
260 
263 
266 
269 
274 
277 
280 
283 
287 
290 
293 
296 
299 
304 
309 
310 public:
312  static void enableAllocationFailure(int count = 1);
314  static void disableAllocationFailure() { _forceAllocationFailure = false; }
315 
316 private:
317  static bool _forceAllocationFailure;
318  static int _forceAllocationFailureCount;
319  static int _forceAllocationFailureModulo;
320 
321 };
322 
323 ML_END_NAMESPACE
324 
325 #endif //of __mlTileRequest_H
326 
A class that allows to incrementally iterate over all ids of pages have an intersection with a given ...
A cursor to create page and tile requests in an iterative manner, to allow breaking/resuming at any t...
Virtual interface for queuing PageRequests that are ready for processing.
A PageRequest represents the request for the calculation of a single page of a PagedImage.
Definition: mlPageRequest.h:32
Class which represents an image, which manages properties of an image and image data which is located...
Definition: mlPagedImage.h:70
This class manages/represents a rectangular 6d image region which is organized linearly in memory.
Definition: mlSubImage.h:75
A TileRequest either represents the input sub image that is needed by a PageRequest or if it is a roo...
Definition: mlTileRequest.h:50
void createInputPageIds()
Creates the pageids for all required input pages.
int getProcessingScope() const
Get the assigned processing scope.
bool isBlockedByMemoryImage()
Checks whether the tile request is blocked by a pending memory image being calculated by another Tile...
void setProcessingScope(int scope)
Get the assigned processing scope.
static void enableAllocationFailure(int count=1)
Enables failing on every count allocation.
void freeData()
Frees the allocated data using SubImage::free(), except if the AllocationPolicy is UserAllocation.
bool propagateCancellationDownIfRequestNotNeededAnymore()
Recursively walks up to all tree roots and checks wether they are cancelled.
void forgetData()
Tells the tile to forget its data so that it is not freed in freeData()
int _processingScope
the processing scope
void allocateData()
Allocates the data using the internal AllocationPolicy.
static TileRequest * allocate()
Tile requests are allocated via the allocate method, they can not be created with new.
double getProgress() const
Returns the progress of this tile (TODO: not very detailed yet, only the ratio of copied/total pages)...
TileRequestFinishedCB * _internalFinishedCB
Callback to signal that the TileRequest has finished.
bool _readOnlyInputTile
Flag that the TileRequest should try to not copy data, since it will not be written to.
PageIDIterator _inputPageIds
Since a tile can have a lot of page requests, we use a PageIdIterator to generate the ids on the fly.
bool copyDataFromSubImg(SubImage &pageImage)
Copies the data from the given image (if in read-only mode, the data might as well be stored instead ...
void sendTileRequestFinished(PageRequestQueueInterface &queue)
Tells the dependend page requests that the tile request has finished.
void setUseTileReadOnly(bool flag)
This allows to make read-only use of input pages or memory image if box/datatype match and shift/scal...
MLint _inputPagesNeeded
Overall number of pages needed (which is getNumPages() of _inputPageIds at the beginning and will dec...
bool hasFinished() const
Returns if the request has finished (If an error happened, this returns true as well).
bool _tileWillBecomeMemoryImage
Flag that the TileRequest should become the MemoryImage when it has finished.
PagedImage * _image
The image from which the data should be requested.
void setInternalTileRequestFinishedCB(TileRequestFinishedCB *cb, void *data)
Sets the internal tile request finished cb (NOTE: this should only be used by the request processor)
void emitFinishedCallback()
Calls the finished callbacks.
void propagateErrorUpwards(MLErrorCode error)
Propagates an error upwards through the PageRequest it depends on.
MLint _traversalCursorPosition
Current _inputPageIds position to indicate the next page request to create.
void setError(MLErrorCode error)
Sets the error that happened.
static void disableAllocationFailure()
Disables allocation failure (default!)
Mutex _inputPagesNeededMutex
TODO: replace above with atomic counter and remove the mutex.
AllocationPolicy getAllocationPolicy() const
Returns the allocation policy.
bool hasError() const
Returns if the request has an error (and the data is thus unusable/invalid).
MLErrorCode _error
The current error state.
void updateSourceImageExtent()
Update the source image extent according to the image.
void setTileRequestFinishedCB(TileRequestFinishedCB *cb, void *data)
Sets the tile request finished cb (NOTE: in the current implementation, the TileRequest may NOT be de...
static void deallocate(TileRequest *request)
Tile requests are deallocated with the deallocate method, they can not be deleted directly.
void collectPageRequestsWithErrors(std::set< PageRequest * > &result)
Collects all page requests that have error()!=ML_RESULT_OK up to the roots of the tree.
bool prepareForCursorVisit()
This is called before a cursor steps down into the TileRequest and may return false,...
void setAllocationPolicy(AllocationPolicy policy)
Sets which allocation policy should be used.
void setNeededBy(PageRequest *request)
Stores the PageRequest which needs this TileRequest.
AllocationPolicy
Defines how the TileRequest will allocate its memory.
Definition: mlTileRequest.h:86
MLErrorCode getError() const
Returns the error that happened (or ML_RESULT_OK).
bool intersectsPagedImage() const
Returns if the request has an intersection with the paged image.
const SubImageBox & getBox() const
Get the box that this tile request covers.
PageRequest * _neededByPageRequest
The PageRequest that depends on this TileRequest (or NULL if it is a root TileRequest).
SubImage _subImage
The sub image that represents the TileRequest's box,datatype and data.
const SubImage & getSubImage() const
Returns the stored sub image (including the data pointer).
MLErrorCode updateImageProperties()
Updates the image properties of the complete graph stating at this tile request via the host.
PageRequest * createPageRequest(MLint pageId, PageRequestQueueInterface &queue)
Creates a new page request (if necessary, otherwise returns NULL) and queue it if it has not dependen...
void init(PagedImage *inputImage, const SubImageBox &box, MLDataType dataType, const ScaleShiftData &scaleShift, bool readOnlyInputTile=false, bool tryToBecomeMemoryImage=false)
Creates a TileRequest for inputImage with given box, dataType and scaleShift.
TileRequestFinishedCB * _finishedCB
Callback to signal that the TileRequest has finished.
AllocationPolicy _allocationPolicy
Defines which allocation method to use.
void * _internalFinishedCBData
Callback data to signal that the TileRequest has finished.
ScaleShiftData _scaleShiftData
The additional scale/shift information.
void setExternalDataBuffer(void *data)
This allows to set the data buffer from an external buffer.
void pageRequestFinished(SubImage &pageImage, PageRequestQueueInterface &queue)
Called by all finished PageRequests, which may be copied to output buffer.
void * _finishedCBData
Callback data to signal that the TileRequest has finished.
static void clearFreeList()
Clear the internal free list of deallocated TileRequests.
MLint32 MLDataType
MLDataType.
Definition: mlTypeDefs.h:684
MLint32 MLErrorCode
Type of an ML Error code.
Definition: mlTypeDefs.h:818
#define ML_RESULT_OK
No error. Everything seems to be okay.
Definition: mlTypeDefs.h:826
boost::mutex Mutex
Defines a non-recursive mutex.
Definition: mlMutex.h:39
MLint64 MLint
A signed ML integer type with at least 64 bits used for index calculations on very large images even ...
Definition: mlTypeDefs.h:578
void TileRequestFinishedCB(void *data, TileRequest *request)
Callback for a finished TileRequest.
Definition: mlTileRequest.h:34