SheafSystem  0.0.0.0
storage_agent.h
1 
2 //
3 // Copyright (c) 2014 Limit Point Systems, Inc.
4 //
5 // Licensed under the Apache License, Version 2.0 (the "License");
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 //
17 
18 // Interface for class storage_agent
19 
20 #ifndef STORAGE_AGENT_H
21 #define STORAGE_AGENT_H
22 
23 #ifndef SHEAF_DLL_SPEC_H
24 #include "SheafSystem/sheaf_dll_spec.h"
25 #endif
26 
27 #ifndef ANY_H
28 #include "SheafSystem/any.h"
29 #endif
30 
31 #ifndef POSET_BOUNDS_DESCRIPTOR_H
32 #include "SheafSystem/poset_bounds_descriptor.h"
33 #endif
34 
35 #ifndef RECORD_MAP_H
36 #include "SheafSystem/record_map.h"
37 #endif
38 
39 #ifndef SHEAF_FILE_H
40 #include "SheafSystem/sheaf_file.h"
41 #endif
42 
43 #ifndef STD_CTIME_H
44 #include "SheafSystem/std_ctime.h"
45 #endif
46 
47 #ifndef STD_SET_H
48 #include "SheafSystem/std_set.h"
49 #endif
50 
51 #ifndef STD_STRING_H
52 #include "SheafSystem/std_string.h"
53 #endif
54 
55 namespace sheaf
56 {
57 
58 class data_type_aliases_record;
59 class member_names_record;
60 class member_record;
61 class namespace_poset;
62 class poset;
63 class poset_data_type_map;
64 class poset_general_record;
65 class poset_scaffold;
66 class abstract_poset_member;
67 class subposet_names_record;
68 class poset_state_handle;
69 
74 class SHEAF_DLL_SPEC storage_agent : public any
75 {
76 
77  friend class poset_scaffold;
78  friend class dof_tuple_record_set;
79 
80 public:
81 
82  // CANONICAL MEMBERS
83 
88  storage_agent();
89 
94  storage_agent(const storage_agent& xother);
95 
101  virtual storage_agent* clone() const;
102 
106  virtual ~storage_agent();
107 
111  virtual bool invariant() const;
112 
116  virtual bool is_ancestor_of(const any* other) const;
117 
118  // ===========================================================
119  // STORAGE_AGENT FACET
120  // ===========================================================
121 
127  storage_agent(const std::string& xfile_name,
128  sheaf_file::access_mode xmode = sheaf_file::READ_WRITE,
129  bool xclobber = true,
130  bool xenable_error_report = false);
131 
135 
136  sheaf_file& file();
137 
141 
142  const sheaf_file& file() const;
143 
147  bool file_is_read_accessible() const;
148 
152  bool file_is_read_only_accessible() const;
153 
157  bool file_is_read_write_accessible() const;
158 
162  const std::string& file_id_space_name() const;
163 
168  void reset_time();
169 
174  clock_t time() const;
175 
176 
177  // CONSTANTS FOR ACCESS ROUTINE ARGUMENTS
178 
182  static const bool COMMIT;
183 
187  static const bool ABORT;
188 
192  static const bool RETAIN_READ;
193 
197  static const bool RELEASE_ALL;
198 
199 
200 
201  // ===========================================================
202  // NAMESPACE_POSET FACET
203  // ===========================================================
204 
208  void read_entire(namespace_poset& xns);
209 
213  void read_remainder(namespace_poset& xns);
214 
218  void read(namespace_poset& xns);
219 
223  void write(namespace_poset& xns);
224 
229  void write_entire(namespace_poset& xns);
230 
234  void write_remainder(const namespace_poset& xns);
235 
236 
237  // ===========================================================
238  // GENERAL POSET FACET
239  // ===========================================================
240 
245  void read(poset_state_handle& xposet,
246  const poset_bounds_descriptor& xrow_bounds =
248  const poset_bounds_descriptor& xcol_bounds =
250 
254  void read_toc(poset_state_handle& xposet);
255 
259  void read_index(poset_state_handle& xposet);
260 
264  void read_row_decomposition(poset_state_handle& xposet,
265  const scoped_index& xdecomp_id);
266 
273  void write(poset_state_handle& xposet,
276  bool xretain_read_access = false);
277 
283  void write_toc(poset_state_handle& xposet, const scoped_index& xtoc_id);
284 
288  void write_row_decomposition(poset_state_handle& xposet,
289  const scoped_index& xdecomp_id);
290 
295  void write_col_decomposition(poset_state_handle& xposet,
296  const scoped_index& xrow_id,
297  const scoped_index& xdecomp_id);
298 
299  // ===========================================================
300  // DOF_TUPLE FACET
301  // ===========================================================
302 
308  void write_dof_tuple(const abstract_poset_member& xmbr,
309  const scoped_index& xcol_ub_id,
310  const scoped_index& xdecomp_id);
311 
315  void commit_dof_tuple_transaction(const abstract_poset_member& xmbr,
316  const scoped_index& xcol_ub_id,
317  const scoped_index& xdecomp_id);
318 
319  // ===========================================================
320  // TRANSACTION FACET
321  // ===========================================================
322 
326  void begin_read_transaction(namespace_poset& xns);
327 
332  void begin_read_transaction(poset_state_handle& xposet,
333  const poset_bounds_descriptor& xrow_bounds =
335  const poset_bounds_descriptor& xcol_bounds =
337 
344  void begin_read_write_transaction(poset_state_handle& xposet,
345  const poset_bounds_descriptor& xrow_bounds =
347  const poset_bounds_descriptor& xcol_bounds =
349 
353  void begin_write_transaction(namespace_poset& xns);
354 
359  void begin_write_transaction(const poset_state_handle& xposet,
360  const poset_bounds_descriptor& xrow_bounds =
362  const poset_bounds_descriptor& xcol_bounds =
364 
369  void commit_transaction(poset_state_handle& xposet);
370 
374  void end_transaction(poset_state_handle& xposet, bool xcommit = true);
375 
376  // ===========================================================
377  // BUFFER SIZE CONTROL FACET
378  // ===========================================================
379 
384  int member_record_buffer_ub() const;
385 
390  void put_member_record_buffer_ub(int xub);
391 
398  size_t dof_tuple_record_size() const;
399 
403  void put_dof_tuple_record_size(size_t xsize);
404 
410  int dof_tuple_record_buffer_ub() const;
411 
417  void put_dof_tuple_record_buffer_ub(int xub);
418 
419 
420  // ===========================================================
421  // TRANSACTION STATUS FACET
422  // ===========================================================
423 
427  int transaction_ct() const;
428 
433  bool transaction_is_active(pod_index_type xindex) const;
434 
439  bool transaction_is_active(const poset_state_handle& xposet) const;
440 
444  bool read_transaction_is_active(const poset_state_handle& xposet) const;
445 
450  bool write_transaction_is_active(const poset_state_handle& xposet) const;
451 
455  bool read_write_transaction_is_active(poset_state_handle& xposet) const;
456 
460  bool state_is_consistent(const poset_state_handle& xposet) const;
461 
462 
467  {
468  READ,
469  WRITE,
470  READ_WRITE
471  };
472 
476  class SHEAF_DLL_SPEC transaction
477  {
478  public:
479 
484 
488  mutable bool is_read_transaction;
489 
493  mutable bool is_write_transaction;
494 
499 
504 
508  bool operator<(const transaction& xother) const;
509 
513  ~transaction();
514 
518  transaction();
519 
523  transaction(pod_index_type xindex);
524 
529  const poset_state_handle& xposet,
530  const poset_bounds_descriptor& xrow_bounds =
532  const poset_bounds_descriptor& xcol_bounds =
534 
535  };
536 
537 protected:
538 
542  void put_state_is_consistent(poset_state_handle& xposet);
543 
544  // ROUTINES TO SUPPORT INDEPENDENT ACCESS
545 
549  void read_prerequisites(const poset_state_handle& xposet,
550  const poset_bounds_descriptor& xcol_bounds);
551 
555  void write_prerequisites(const poset_scaffold& xscaffold);
556 
560  void initialize_poset_id_spaces_for_write(poset_state_handle& xposet);
561 
566  void initialize_namespace_id_spaces_for_read(namespace_poset& xposet);
567 
573  void initialize_namespace_id_spaces_for_write(namespace_poset& xposet);
574 
578  void clear_all_id_spaces(namespace_poset& xns);
579 
580 
581 private:
582 
587  int _member_record_buffer_ub;
588 
592  size_t _dof_tuple_record_size;
593 
598  int _dof_tuple_record_buffer_ub;
599 
603  sheaf_file _file;
604 
608  std::string _file_id_space_name;
609 
615  std::set<transaction> _active_transactions;
616 
621  clock_t _start_time;
622 
627  const transaction& active_transaction(const poset_state_handle& xposet);
628 
632  void put_active_transaction(transaction& xtransaction);
633 
638  void remove_active_transaction(const poset_state_handle& xposet);
639 
640 };
641 
642 } // namespace sheaf
643 
644 #endif // ifndef STORAGE_AGENT_H
645 
646 
647 
648 
649 
650 
651 
bool is_read_transaction
True if read transaction.
An encapsulation of an HDF file containing sheaf data.
Definition: sheaf_file.h:49
bool is_write_transaction
True if write transaction.
The default name space; a poset which contains other posets as members.
A client handle for a general, abstract partially order set.
access_mode
File access modes.
Definition: sheaf_file.h:111
poset_bounds_descriptor col_bounds
Bounds for the columns accessed in this transaction.
Abstract base class with useful features for all objects.
Definition: any.h:39
pod_index_type target
The index of the target poset of the transaction.
poset_bounds_descriptor row_bounds
Bounds for the rows accessed in this transaction.
transaction_type
Type of access associated with a transaction.
An index within the external ("client") scope of a given id space.
Definition: scoped_index.h:116
static const poset_bounds_descriptor & BOTTOM_TOP
An instance with lb() == {bottom} and ub() == {top}.
A record_set which contains dof tuple records. Supports both record selection and record restriction ...
A description of a (lower, upper) bounds pair for a poset. Specifies a portion of a poset for a bound...
static const bool ABORT
Value to indicate transaction should not be committed.
static const bool RETAIN_READ
Value to indicate read access should be retained.
int_type pod_index_type
The plain old data index type.
Definition: pod_types.h:49
static const bool RELEASE_ALL
Value to indicate read access should not be retained.
static const bool COMMIT
Value to indicate transaction should be committed.
Namespace for the sheaves component of the sheaf system.
A poset specific collection of data converters, various buffers and other data used while transferrin...
An abstract client handle for a member of a poset.
Agent responsible for importing and exporting posets from an external name space which resides on dis...
Definition: storage_agent.h:74