record_set.h

//
// Copyright (c) 2014 Limit Point Systems, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

// Interface for class record_set

#ifndef RECORD_SET_H
#define RECORD_SET_H

#ifndef SHEAF_DLL_SPEC_H
#include "SheafSystem/sheaf_dll_spec.h"
#endif

#ifndef ANY_H
#include "SheafSystem/any.h"
#endif

#ifndef POSET_SCAFFOLD_H
#include "SheafSystem/poset_scaffold.h"
#endif

#ifndef RECORD_INDEX_H
#include "SheafSystem/record_index.h"
#endif

#ifndef STD_HDF5_H
#include "SheafSystem/std_hdf5.h"
#endif

#ifndef STD_STRING_H
#include "SheafSystem/std_string.h"
#endif

namespace sheaf
{

class sheaf_file;
class record;
class poset_data_type_map;


// The hdf buffer is allocated in
// the record set, while the external buffer is currently
// allocated individually in each record, after the length of
// the data has been determined. (This process can and should be
// optimized by some sort of pool allocation scheme for the
// actual data.)
//
// The process for externalizing any of these record sets is the same:
//  allocate the hvl_t buffer in the constructor
//  for each record:
// transfer the poset info to the internal buffer
// initialize the external buffer
// convert the internal buffer to the external buffer
// transfer the external buffer to hdf (i.e. set the hvl_t)
//
// The process for internalizing is essentially the reverse :
//  allocate the hvl_t buffer in the constructor
//  for each record:
// transfer the hdf buffer to the external buffer
//   (i.e. make the external buffer point at the
//   memory allocated by hdf)
// convert the external buffer to the internal buffer
// transfer the internal buffer to the poset
//
//
// The dof_tuple_record_set is different for three reasons:
// 1. Restriction requires random access to individual dofs, not
//    just entire dof tuples. Hence, the dof_tuple_record_set must
//    contain a dataspace of rank 2, the 2 indices being dof_tuple_id
//    and dof id.
// 2. While in general the dofs are of inhomogeneous
//    type and must be implemented as variable length of char, the
//    homogeneous case is an important optimization which must be supported.
//    The data type is thus either variable length of char or some
//    specific primitive type, depending on the case.
// 3. There is no separate internal buffer. The dof tuple itself
//    is used as the internal buffer.
//
//
class SHEAF_DLL_SPEC record_set : public any
{

public:

  // =============================================================================
  // ANY FACET
  // =============================================================================

  virtual record_set* clone() const;

  virtual bool invariant() const;

  virtual bool is_ancestor_of(const any* other) const;


  // =============================================================================
  // RECORD_SET FACET
  // =============================================================================

  record_set(const sheaf_file& xfile, int xrecord_buffer_ub, const poset_scaffold& xscaffold);

  record_set(const record_set& xother);

  virtual ~record_set();

  const sheaf_file& file() const;

  std::string name() const;

  std::string alias() const;

  static const std::string& name_space_alias();

  static const std::string& name_space_prefix();

  virtual const std::string& suffix() const;

  std::string data_set_name(const std::string& xname) const;

  std::string data_set_alias(const std::string& xname) const;

  std::string poset_name() const;

  poset_scaffold& scaffold();

  const poset_scaffold& scaffold() const;

  poset_data_type_map& type_map();

  const poset_data_type_map& type_map() const;

  virtual void open();

  bool is_open() const;

  virtual void close();

  int record_buffer_ct() const;

  void inc_record_buffer_ct();

  void reset_record_buffer_ct();

  int record_buffer_ub() const;

  bool record_buffer_is_empty() const;

  bool record_buffer_is_full() const;

protected:

  virtual hid_t create_dataset() = 0;

  virtual void create_int_data_type() = 0;

  void extend_dataset(const hsize_t* xdims, int xdims_ub);

  void create_alias();

  void set_name_from_alias();


  hid_t hdf_id();

  hid_t ext_dataspace_hdf_id();

  hid_t ext_data_type_hdf_id();

  int ext_dataspace_rank();

  hsize_t ext_dataspace_dim(int xi);

  hid_t int_dataspace_hdf_id();

  hid_t int_data_type_hdf_id();

  // Default constructor;
  // not supported because can not initialize reference data members
  // record_set();

  sheaf_file& _file;

  std::string _name;

  std::string _alias;

  poset_scaffold& _scaffold;

  hid_t _hdf_id;

  hid_t _ext_dataspace_hdf_id;

  hid_t _ext_data_type_hdf_id;

  int _ext_dataspace_rank;

  hsize_t* _ext_dataspace_dims;

  static const hid_t NOT_AN_HDF_ID;

  int _record_buffer_ct;

  int _record_buffer_ub;

  hid_t _int_dataspace_hdf_id;

  hid_t _int_data_type_hdf_id;

  virtual void read_dataset_attributes();

  virtual void write_dataset_attributes();

  void read_attribute(const char*& xatt_values,
                      size_type& xatt_ct,
                      const data_converter* xatt_conv,
                      const std::string& xatt_name);
  void write_attribute(const void* xatt_values,
                       size_type xatt_ct,
                       const data_converter* xatt_conv,
                       const std::string& xatt_name);


};

} // namespace sheaf

#endif // ifndef RECORD_SET_H