openPMD-api
IOTask.hpp
1 /* Copyright 2017-2021 Fabian Koller
2  *
3  * This file is part of openPMD-api.
4  *
5  * openPMD-api is free software: you can redistribute it and/or modify
6  * it under the terms of of either the GNU General Public License or
7  * the GNU Lesser General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * openPMD-api is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU General Public License and the GNU Lesser General Public License
15  * for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * and the GNU Lesser General Public License along with openPMD-api.
19  * If not, see <http://www.gnu.org/licenses/>.
20  */
21 #pragma once
22 
23 #include "openPMD/auxiliary/Export.hpp"
24 #include "openPMD/auxiliary/Variant.hpp"
25 #include "openPMD/backend/Attribute.hpp"
26 #include "openPMD/ChunkInfo.hpp"
27 #include "openPMD/Dataset.hpp"
28 #include "openPMD/IterationEncoding.hpp"
29 
30 #include <memory>
31 #include <map>
32 #include <string>
33 #include <utility>
34 #include <vector>
35 
36 #include "openPMD/Streaming.hpp"
37 
38 
39 namespace openPMD
40 {
41 class AttributableInterface;
42 class Writable;
43 
44 Writable*
45 getWritable(AttributableInterface*);
46 
50 {
51  CREATE_FILE,
52  OPEN_FILE,
53  CLOSE_FILE,
54  DELETE_FILE,
55 
56  CREATE_PATH,
57  CLOSE_PATH,
58  OPEN_PATH,
59  DELETE_PATH,
60  LIST_PATHS,
61 
62  CREATE_DATASET,
63  EXTEND_DATASET,
64  OPEN_DATASET,
65  DELETE_DATASET,
66  WRITE_DATASET,
67  READ_DATASET,
68  LIST_DATASETS,
69  GET_BUFFER_VIEW,
70 
71  DELETE_ATT,
72  WRITE_ATT,
73  READ_ATT,
74  LIST_ATTS,
75 
76  ADVANCE,
77  AVAILABLE_CHUNKS
78 }; // note: if you change the enum members here, please update docs/source/dev/design.rst
79 
80 struct OPENPMDAPI_EXPORT AbstractParameter
81 {
82  virtual ~AbstractParameter() = default;
83  AbstractParameter() = default;
84  //AbstractParameter(AbstractParameter&&) = default;
85 
86  // avoid object slicing
87  AbstractParameter(const AbstractParameter&) = delete;
88  AbstractParameter& operator=(const AbstractParameter&) = delete;
89  virtual std::unique_ptr< AbstractParameter > clone() const = 0;
90 };
91 
100 template< Operation >
101 struct OPENPMDAPI_EXPORT Parameter : public AbstractParameter
102 {
103  Parameter() = delete;
104  Parameter(Parameter const &) = delete;
105  Parameter(Parameter &&) = delete;
106 };
107 
108 template<>
109 struct OPENPMDAPI_EXPORT Parameter< Operation::CREATE_FILE > : public AbstractParameter
110 {
111  Parameter() = default;
112  Parameter(Parameter const & p) :
113  AbstractParameter(), name(p.name), encoding(p.encoding) {}
114 
115  std::unique_ptr< AbstractParameter >
116  clone() const override
117  {
118  return std::unique_ptr< AbstractParameter >(
120  }
121 
122  std::string name = "";
123  IterationEncoding encoding = IterationEncoding::groupBased;
124 };
125 
126 template<>
127 struct OPENPMDAPI_EXPORT Parameter< Operation::OPEN_FILE > : public AbstractParameter
128 {
129  Parameter() = default;
130  Parameter(Parameter const & p) :
131  AbstractParameter(), name(p.name), encoding(p.encoding) {}
132 
133  std::unique_ptr< AbstractParameter >
134  clone() const override
135  {
136  return std::unique_ptr< AbstractParameter >(
138  }
139 
140  std::string name = "";
141  /*
142  * The backends might need to ensure availability of certain features
143  * for some iteration encodings, e.g. availability of ADIOS steps for
144  * variableBased encoding.
145  */
146  IterationEncoding encoding = IterationEncoding::groupBased;
147 };
148 
149 template<>
150 struct OPENPMDAPI_EXPORT Parameter< Operation::CLOSE_FILE > : public AbstractParameter
151 {
152  Parameter() = default;
153  Parameter( Parameter const & ) : AbstractParameter() {}
154 
155  std::unique_ptr< AbstractParameter >
156  clone() const override
157  {
158  return std::unique_ptr< AbstractParameter >(
159  new Parameter< Operation::CLOSE_FILE >( *this ) );
160  }
161 };
162 
163 template<>
164 struct OPENPMDAPI_EXPORT Parameter< Operation::DELETE_FILE > : public AbstractParameter
165 {
166  Parameter() = default;
167  Parameter(Parameter const & p) : AbstractParameter(), name(p.name) {}
168 
169  std::unique_ptr< AbstractParameter >
170  clone() const override
171  {
172  return std::unique_ptr< AbstractParameter >(
174  }
175 
176  std::string name = "";
177 };
178 
179 template<>
180 struct OPENPMDAPI_EXPORT Parameter< Operation::CREATE_PATH > : public AbstractParameter
181 {
182  Parameter() = default;
183  Parameter(Parameter const & p) : AbstractParameter(), path(p.path) {}
184 
185  std::unique_ptr< AbstractParameter >
186  clone() const override
187  {
188  return std::unique_ptr< AbstractParameter >(
190  }
191 
192  std::string path = "";
193 };
194 
195 template<>
196 struct OPENPMDAPI_EXPORT Parameter< Operation::CLOSE_PATH > : public AbstractParameter
197 {
198  Parameter() = default;
199  Parameter( Parameter const & ) : AbstractParameter()
200  {
201  }
202 
203  Parameter &
204  operator=( Parameter const & )
205  {
206  return *this;
207  }
208 
209  std::unique_ptr< AbstractParameter >
210  clone() const override
211  {
212  return std::unique_ptr< AbstractParameter >(
213  new Parameter< Operation::CLOSE_PATH >( *this ) );
214  }
215 };
216 
217 template<>
218 struct OPENPMDAPI_EXPORT Parameter< Operation::OPEN_PATH > : public AbstractParameter
219 {
220  Parameter() = default;
221  Parameter(Parameter const & p) : AbstractParameter(), path(p.path) {}
222 
223  std::unique_ptr< AbstractParameter >
224  clone() const override
225  {
226  return std::unique_ptr< AbstractParameter >(
228  }
229 
230  std::string path = "";
231 };
232 
233 template<>
234 struct OPENPMDAPI_EXPORT Parameter< Operation::DELETE_PATH > : public AbstractParameter
235 {
236  Parameter() = default;
237  Parameter(Parameter const & p) : AbstractParameter(), path(p.path) {}
238 
239  std::unique_ptr< AbstractParameter >
240  clone() const override
241  {
242  return std::unique_ptr< AbstractParameter >(
244  }
245 
246  std::string path = "";
247 };
248 
249 template<>
250 struct OPENPMDAPI_EXPORT Parameter< Operation::LIST_PATHS > : public AbstractParameter
251 {
252  Parameter() = default;
253  Parameter(Parameter const & p) : AbstractParameter(), paths(p.paths) {}
254 
255  std::unique_ptr< AbstractParameter >
256  clone() const override
257  {
258  return std::unique_ptr< AbstractParameter >(
260  }
261 
262  std::shared_ptr< std::vector< std::string > > paths
263  = std::make_shared< std::vector< std::string > >();
264 };
265 
266 template<>
267 struct OPENPMDAPI_EXPORT Parameter< Operation::CREATE_DATASET > : public AbstractParameter
268 {
269  Parameter() = default;
270  Parameter(Parameter const & p) : AbstractParameter(),
271  name(p.name), extent(p.extent), dtype(p.dtype),
272  chunkSize(p.chunkSize), compression(p.compression),
273  transform(p.transform), options(p.options) {}
274 
275  std::unique_ptr< AbstractParameter >
276  clone() const override
277  {
278  return std::unique_ptr< AbstractParameter >(
280  }
281 
282  std::string name = "";
283  Extent extent = {};
284  Datatype dtype = Datatype::UNDEFINED;
285  Extent chunkSize = {};
286  std::string compression = "";
287  std::string transform = "";
288  std::string options = "{}";
289 };
290 
291 template<>
292 struct OPENPMDAPI_EXPORT Parameter< Operation::EXTEND_DATASET > : public AbstractParameter
293 {
294  Parameter() = default;
295  Parameter(Parameter const & p) : AbstractParameter(), extent(p.extent) {}
296 
297  std::unique_ptr< AbstractParameter >
298  clone() const override
299  {
300  return std::unique_ptr< AbstractParameter >(
302  }
303 
304  Extent extent = {};
305 };
306 
307 template<>
308 struct OPENPMDAPI_EXPORT Parameter< Operation::OPEN_DATASET > : public AbstractParameter
309 {
310  Parameter() = default;
311  Parameter(Parameter const & p) : AbstractParameter(),
312  name(p.name), dtype(p.dtype), extent(p.extent) {}
313 
314  std::unique_ptr< AbstractParameter >
315  clone() const override
316  {
317  return std::unique_ptr< AbstractParameter >(
319  }
320 
321  std::string name = "";
322  std::shared_ptr< Datatype > dtype
323  = std::make_shared< Datatype >();
324  std::shared_ptr< Extent > extent
325  = std::make_shared< Extent >();
326 };
327 
328 template<>
329 struct OPENPMDAPI_EXPORT Parameter< Operation::DELETE_DATASET > : public AbstractParameter
330 {
331  Parameter() = default;
332  Parameter(Parameter const & p) : AbstractParameter(), name(p.name) {}
333 
334  std::unique_ptr< AbstractParameter >
335  clone() const override
336  {
337  return std::unique_ptr< AbstractParameter >(
339  }
340 
341  std::string name = "";
342 };
343 
344 template<>
345 struct OPENPMDAPI_EXPORT Parameter< Operation::WRITE_DATASET > : public AbstractParameter
346 {
347  Parameter() = default;
349  extent(p.extent), offset(p.offset), dtype(p.dtype),
350  data(p.data) {}
351 
352  Parameter& operator=(const Parameter& p) {
353  this->extent = p.extent;
354  this->offset = p.offset;
355  this->dtype = p.dtype;
356  this->data = p.data;
357  return *this;
358  }
359 
360  std::unique_ptr< AbstractParameter >
361  clone() const override
362  {
363  return std::unique_ptr< AbstractParameter >(
365  }
366 
367  Extent extent = {};
368  Offset offset = {};
369  Datatype dtype = Datatype::UNDEFINED;
370  std::shared_ptr< void const > data = nullptr;
371 };
372 
373 template<>
374 struct OPENPMDAPI_EXPORT Parameter< Operation::READ_DATASET > : public AbstractParameter
375 {
376  Parameter() = default;
378  extent(p.extent), offset(p.offset), dtype(p.dtype),
379  data(p.data) {}
380 
381  Parameter& operator=(const Parameter &p) {
382  this->extent = p.extent;
383  this->offset = p.offset;
384  this->dtype = p.dtype;
385  this->data = p.data;
386  return *this;
387  }
388 
389  std::unique_ptr< AbstractParameter >
390  clone() const override
391  {
392  return std::unique_ptr< AbstractParameter >(
394  }
395 
396  Extent extent = {};
397  Offset offset = {};
398  Datatype dtype = Datatype::UNDEFINED;
399  std::shared_ptr< void > data = nullptr;
400 };
401 
402 template<>
403 struct OPENPMDAPI_EXPORT Parameter< Operation::LIST_DATASETS > : public AbstractParameter
404 {
405  Parameter() = default;
406  Parameter(Parameter const & p) : AbstractParameter(),
407  datasets(p.datasets) {}
408 
409  std::unique_ptr< AbstractParameter >
410  clone() const override
411  {
412  return std::unique_ptr< AbstractParameter >(
414  }
415 
416  std::shared_ptr< std::vector< std::string > > datasets
417  = std::make_shared< std::vector< std::string > >();
418 };
419 
420 template<>
421 struct OPENPMDAPI_EXPORT Parameter< Operation::GET_BUFFER_VIEW > : public AbstractParameter
422 {
423  Parameter() = default;
424  Parameter(Parameter const & p) : AbstractParameter(),
425  offset(p.offset), extent(p.extent), dtype(p.dtype), update(p.update),
426  out(p.out)
427  {}
428 
429  std::unique_ptr< AbstractParameter >
430  clone() const override
431  {
432  return std::unique_ptr< AbstractParameter >(
434  }
435 
436  // in parameters
437  Offset offset;
438  Extent extent;
439  Datatype dtype = Datatype::UNDEFINED;
440  bool update = false;
441  // out parameters
442  struct OutParameters
443  {
444  bool backendManagedBuffer = false;
445  unsigned viewIndex = 0;
446  void *ptr = nullptr;
447  };
448  std::shared_ptr< OutParameters > out = std::make_shared< OutParameters >();
449 };
450 
451 template<>
452 struct OPENPMDAPI_EXPORT Parameter< Operation::DELETE_ATT > : public AbstractParameter
453 {
454  Parameter() = default;
455  Parameter(Parameter const & p) : AbstractParameter(), name(p.name) {}
456 
457  std::unique_ptr< AbstractParameter >
458  clone() const override
459  {
460  return std::unique_ptr< AbstractParameter >(
462  }
463 
464  std::string name = "";
465 };
466 
467 template<>
468 struct OPENPMDAPI_EXPORT Parameter< Operation::WRITE_ATT > : public AbstractParameter
469 {
470  Parameter() = default;
471  Parameter(Parameter const & p) : AbstractParameter(),
472  name(p.name), dtype(p.dtype), resource(p.resource) {}
473 
474  std::unique_ptr< AbstractParameter >
475  clone() const override
476  {
477  return std::unique_ptr< AbstractParameter >(
479  }
480 
481  std::string name = "";
482  Datatype dtype = Datatype::UNDEFINED;
483  Attribute::resource resource;
484 };
485 
486 template<>
487 struct OPENPMDAPI_EXPORT Parameter< Operation::READ_ATT > : public AbstractParameter
488 {
489  Parameter() = default;
490  Parameter(Parameter const & p) : AbstractParameter(),
491  name(p.name), dtype(p.dtype), resource(p.resource) {}
492 
493  Parameter& operator=(const Parameter &p) {
494  this->name = p.name;
495  this->dtype = p.dtype;
496  this->resource = p.resource;
497  return *this;
498  }
499 
500  std::unique_ptr< AbstractParameter >
501  clone() const override
502  {
503  return std::unique_ptr< AbstractParameter >(
505  }
506 
507  std::string name = "";
508  std::shared_ptr< Datatype > dtype
509  = std::make_shared< Datatype >();
510  std::shared_ptr< Attribute::resource > resource
511  = std::make_shared< Attribute::resource >();
512 };
513 
514 template<>
515 struct OPENPMDAPI_EXPORT Parameter< Operation::LIST_ATTS > : public AbstractParameter
516 {
517  Parameter() = default;
518  Parameter(Parameter const & p) : AbstractParameter(),
519  attributes(p.attributes) {}
520 
521  std::unique_ptr< AbstractParameter >
522  clone() const override
523  {
524  return std::unique_ptr< AbstractParameter >(
526  }
527 
528  std::shared_ptr< std::vector< std::string > > attributes
529  = std::make_shared< std::vector< std::string > >();
530 };
531 
532 template<>
533 struct OPENPMDAPI_EXPORT Parameter< Operation::ADVANCE > : public AbstractParameter
534 {
535  Parameter() = default;
536  Parameter( Parameter const & p )
537  : AbstractParameter(), mode( p.mode ), status( p.status )
538  {
539  }
540 
541  std::unique_ptr< AbstractParameter >
542  clone() const override
543  {
544  return std::unique_ptr< AbstractParameter >(
545  new Parameter< Operation::ADVANCE >( *this ) );
546  }
547 
551  std::shared_ptr< AdvanceStatus > status =
552  std::make_shared< AdvanceStatus >( AdvanceStatus::OK );
553 };
554 
555 template<>
556 struct OPENPMDAPI_EXPORT Parameter< Operation::AVAILABLE_CHUNKS >
557  : public AbstractParameter
558 {
559  Parameter() = default;
560  Parameter( Parameter const & p ) : AbstractParameter(), chunks( p.chunks )
561  {
562  }
563 
564  Parameter &
565  operator=( Parameter const & p )
566  {
567  chunks = p.chunks;
568  return *this;
569  }
570 
571  std::unique_ptr< AbstractParameter >
572  clone() const override
573  {
574  return std::unique_ptr< AbstractParameter >(
576  }
577 
578  // output parameter
579  std::shared_ptr< ChunkTable > chunks = std::make_shared< ChunkTable >();
580 };
581 
590 class OPENPMDAPI_EXPORT IOTask
591 {
592 public:
599  template< Operation op >
600  explicit IOTask(Writable* w,
601  Parameter< op > const & p)
602  : writable{w},
603  operation{op},
604  parameter{p.clone()}
605  { }
606 
607  template< Operation op >
608  explicit IOTask(AttributableInterface* a,
609  Parameter< op > const & p)
610  : writable{getWritable(a)},
611  operation{op},
612  parameter{p.clone()}
613  { }
614 
615  explicit IOTask(IOTask const & other) :
616  writable{other.writable},
617  operation{other.operation},
618  parameter{other.parameter}
619  {}
620 
621  IOTask& operator=(IOTask const & other)
622  {
623  writable = other.writable;
624  operation = other.operation;
625  parameter = other.parameter;
626  return *this;
627  }
628 
629  Writable* writable;
630  Operation operation;
631  std::shared_ptr< AbstractParameter > parameter;
632 }; // IOTask
633 } // namespace openPMD
Self-contained description of a single IO operation.
Definition: IOTask.hpp:590
AdvanceMode mode
input parameter
Definition: IOTask.hpp:549
AdvanceMode
In step-based mode (i.e.
Definition: Streaming.hpp:33
Datatype
Concrete datatype of an object available at runtime.
Definition: Datatype.hpp:45
Public definitions of openPMD-api.
Definition: Date.cpp:29
Layer to mirror structure of logical data and persistent data in file.
Definition: Writable.hpp:64
Typesafe description of all required arguments for a specified Operation.
Definition: IOTask.hpp:101
OPENPMDAPI_EXPORT_ENUM_CLASS(Operation)
Type of IO operation between logical and persistent data.
Definition: IOTask.hpp:49
Layer to manage storage of attributes associated with file objects.
Definition: Attributable.hpp:93
Definition: IOTask.hpp:80
IterationEncoding
Encoding scheme of an Iterations Series&#39;.
Definition: IterationEncoding.hpp:32
IOTask(Writable *w, Parameter< op > const &p)
Constructor for self-contained description of single IO operation.
Definition: IOTask.hpp:600