storage_agent.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 storage_agent

#ifndef STORAGE_AGENT_H
#define STORAGE_AGENT_H

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

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

#ifndef POSET_BOUNDS_DESCRIPTOR_H
#include "SheafSystem/poset_bounds_descriptor.h"
#endif

#ifndef RECORD_MAP_H
#include "SheafSystem/record_map.h"
#endif

#ifndef SHEAF_FILE_H
#include "SheafSystem/sheaf_file.h"
#endif

#ifndef STD_CTIME_H
#include "SheafSystem/std_ctime.h"
#endif

#ifndef STD_SET_H
#include "SheafSystem/std_set.h"
#endif

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

namespace sheaf
{

class data_type_aliases_record;
class member_names_record;
class member_record;
class namespace_poset;
class poset;
class poset_data_type_map;
class poset_general_record;
class poset_scaffold;
class abstract_poset_member;
class subposet_names_record;
class poset_state_handle;

class SHEAF_DLL_SPEC storage_agent : public any
{

  friend class poset_scaffold;
  friend class dof_tuple_record_set;

public:

  // CANONICAL MEMBERS

  storage_agent();

  storage_agent(const storage_agent& xother);

  virtual storage_agent* clone() const;

  virtual ~storage_agent();

  virtual bool invariant() const;

  virtual bool is_ancestor_of(const any* other) const;

  // ===========================================================
  // STORAGE_AGENT FACET
  // ===========================================================

  storage_agent(const std::string& xfile_name,
                sheaf_file::access_mode xmode = sheaf_file::READ_WRITE,
                bool xclobber = true,
                bool xenable_error_report = false);


  sheaf_file& file();
  

  const sheaf_file& file() const;

  bool file_is_read_accessible() const;

  bool file_is_read_only_accessible() const;

  bool file_is_read_write_accessible() const;

  const std::string& file_id_space_name() const;

  void reset_time();

  clock_t time() const;


  // CONSTANTS FOR ACCESS ROUTINE ARGUMENTS

  static const bool COMMIT;

  static const bool ABORT;

  static const bool RETAIN_READ;

  static const bool RELEASE_ALL;



  // ===========================================================
  // NAMESPACE_POSET FACET
  // ===========================================================

  void read_entire(namespace_poset& xns);

  void read_remainder(namespace_poset& xns);

  void read(namespace_poset& xns);

  void write(namespace_poset& xns);

  void write_entire(namespace_poset& xns);

  void write_remainder(const namespace_poset& xns);


  // ===========================================================
  // GENERAL POSET FACET
  // ===========================================================

  void read(poset_state_handle& xposet,
            const poset_bounds_descriptor& xrow_bounds =
              poset_bounds_descriptor::BOTTOM_TOP,
            const poset_bounds_descriptor& xcol_bounds =
              poset_bounds_descriptor::BOTTOM_TOP);

  void read_toc(poset_state_handle& xposet);

  void read_index(poset_state_handle& xposet);

  void read_row_decomposition(poset_state_handle& xposet,
                  const scoped_index& xdecomp_id);

  void write(poset_state_handle& xposet,
             const poset_bounds_descriptor& xrow_bounds = poset_bounds_descriptor::BOTTOM_TOP,
             const poset_bounds_descriptor& xcol_bounds = poset_bounds_descriptor::BOTTOM_TOP,
             bool xretain_read_access = false);

  void write_toc(poset_state_handle& xposet, const scoped_index& xtoc_id);

  void write_row_decomposition(poset_state_handle& xposet,
                               const scoped_index& xdecomp_id);

  void write_col_decomposition(poset_state_handle& xposet,
                               const scoped_index& xrow_id,
                               const scoped_index& xdecomp_id);

  // ===========================================================
  // DOF_TUPLE FACET
  // ===========================================================

  void write_dof_tuple(const abstract_poset_member& xmbr,
                       const scoped_index& xcol_ub_id,
                       const scoped_index& xdecomp_id);

  void commit_dof_tuple_transaction(const abstract_poset_member& xmbr,
                                    const scoped_index& xcol_ub_id,
                                    const scoped_index& xdecomp_id);

  // ===========================================================
  // TRANSACTION FACET
  // ===========================================================

  void begin_read_transaction(namespace_poset& xns);

  void begin_read_transaction(poset_state_handle& xposet,
                              const poset_bounds_descriptor& xrow_bounds =
                                poset_bounds_descriptor::BOTTOM_TOP,
                              const poset_bounds_descriptor& xcol_bounds =
                                poset_bounds_descriptor::BOTTOM_TOP);

  void begin_read_write_transaction(poset_state_handle& xposet,
                                    const poset_bounds_descriptor& xrow_bounds =
                                      poset_bounds_descriptor::BOTTOM_TOP,
                                    const poset_bounds_descriptor& xcol_bounds =
                                      poset_bounds_descriptor::BOTTOM_TOP);

  void begin_write_transaction(namespace_poset& xns);

  void begin_write_transaction(const poset_state_handle& xposet,
                               const poset_bounds_descriptor& xrow_bounds =
                                 poset_bounds_descriptor::BOTTOM_TOP,
                               const poset_bounds_descriptor& xcol_bounds =
                                 poset_bounds_descriptor::BOTTOM_TOP);

  void commit_transaction(poset_state_handle& xposet);

  void end_transaction(poset_state_handle& xposet, bool xcommit = true);

  // ===========================================================
  // BUFFER SIZE CONTROL FACET
  // ===========================================================

  int member_record_buffer_ub() const;

  void put_member_record_buffer_ub(int xub);

  size_t dof_tuple_record_size() const;

  void put_dof_tuple_record_size(size_t xsize);

  int dof_tuple_record_buffer_ub() const;

  void put_dof_tuple_record_buffer_ub(int xub);


  // ===========================================================
  // TRANSACTION STATUS FACET
  // ===========================================================

  int transaction_ct() const;

  bool transaction_is_active(pod_index_type xindex) const;

  bool transaction_is_active(const poset_state_handle& xposet) const;

  bool read_transaction_is_active(const poset_state_handle& xposet) const;

  bool write_transaction_is_active(const poset_state_handle& xposet) const;

  bool read_write_transaction_is_active(poset_state_handle& xposet) const;

  bool state_is_consistent(const poset_state_handle& xposet) const;


  enum transaction_type
  {
    READ,
    WRITE,
    READ_WRITE
  };

  class SHEAF_DLL_SPEC transaction
  {
  public:

    pod_index_type target;

    mutable bool is_read_transaction;

    mutable bool is_write_transaction;

    mutable poset_bounds_descriptor row_bounds;

    mutable poset_bounds_descriptor col_bounds;

    bool operator<(const transaction& xother) const;

    ~transaction();

    transaction();

    transaction(pod_index_type xindex);

    transaction(transaction_type xtype,
                const poset_state_handle& xposet,
                const poset_bounds_descriptor& xrow_bounds =
                  poset_bounds_descriptor::BOTTOM_TOP,
                const poset_bounds_descriptor& xcol_bounds =
                  poset_bounds_descriptor::BOTTOM_TOP);

  };

protected:

  void put_state_is_consistent(poset_state_handle& xposet);

  // ROUTINES TO SUPPORT INDEPENDENT ACCESS

  void read_prerequisites(const poset_state_handle& xposet,
                          const poset_bounds_descriptor& xcol_bounds);

  void write_prerequisites(const poset_scaffold& xscaffold);

  void initialize_poset_id_spaces_for_write(poset_state_handle& xposet);

  void initialize_namespace_id_spaces_for_read(namespace_poset& xposet);

  void initialize_namespace_id_spaces_for_write(namespace_poset& xposet);

  void clear_all_id_spaces(namespace_poset& xns);


private:

  int _member_record_buffer_ub;

  size_t _dof_tuple_record_size;

  int _dof_tuple_record_buffer_ub;

  sheaf_file _file;

  std::string _file_id_space_name;

  std::set<transaction> _active_transactions;

  clock_t _start_time;

  const transaction& active_transaction(const poset_state_handle& xposet);

  void put_active_transaction(transaction& xtransaction);

  void remove_active_transaction(const poset_state_handle& xposet);
    
};
  
} // namespace sheaf

#endif // ifndef STORAGE_AGENT_H