From c15da67ba6cc5707f94c6e796eabd3d97ceb8491 Mon Sep 17 00:00:00 2001 From: Gav Wood Date: Sat, 20 Dec 2014 15:46:33 +0100 Subject: [PATCH] Documentation, repotting. --- libdevcore/Diff.h | 52 +++++++++++++++++++++++++++++++++++ libethereum/AccountDiff.cpp | 16 ++++++++--- libethereum/AccountDiff.h | 55 +++++++++++++++++++++---------------- 3 files changed, 96 insertions(+), 27 deletions(-) create mode 100644 libdevcore/Diff.h diff --git a/libdevcore/Diff.h b/libdevcore/Diff.h new file mode 100644 index 000000000..fa5f6be2d --- /dev/null +++ b/libdevcore/Diff.h @@ -0,0 +1,52 @@ +/* + This file is part of cpp-ethereum. + + cpp-ethereum is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + cpp-ethereum is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with cpp-ethereum. If not, see . +*/ +/** @file Diff.h + * @author Gav Wood + * @date 2014 + */ + +#pragma once + +namespace dev +{ + +enum class ExistDiff +{ + Same, + New, + Dead +}; + +template +class Diff +{ +public: + Diff() {} + Diff(T _from, T _to): m_from(_from), m_to(_to) {} + + T const& from() const { return m_from; } + T const& to() const { return m_to; } + + explicit operator bool() const { return m_from != m_to; } + +private: + T m_from; + T m_to; +}; + +} + diff --git a/libethereum/AccountDiff.cpp b/libethereum/AccountDiff.cpp index c434086fa..ae82e18d9 100644 --- a/libethereum/AccountDiff.cpp +++ b/libethereum/AccountDiff.cpp @@ -33,11 +33,19 @@ AccountChange AccountDiff::changeType() const return exist ? exist.from() ? AccountChange::Deletion : AccountChange::Creation : (bn && sc) ? AccountChange::All : bn ? AccountChange::Intrinsic: sc ? AccountChange::CodeStorage : AccountChange::None; } -char const* AccountDiff::lead() const +char const* dev::lead(AccountChange _c) const { - bool bn = (balance || nonce); - bool sc = (!storage.empty() || code); - return exist ? exist.from() ? "XXX" : "+++" : (bn && sc) ? "***" : bn ? " * " : sc ? "* *" : " "; + switch (_c) + { + case AccountChange::None: return " "; + case AccountChange::Creation: return "+++"; + case AccountChange::Deletion: return "XXX"; + case AccountChange::Intrinsic: return " * "; + case AccountChange::CodeStorage: return "* *"; + case AccountChange::All: return "***"; + } + assert(false); + return ""; } namespace dev { diff --git a/libethereum/AccountDiff.h b/libethereum/AccountDiff.h index d4c30ead5..0c0ede4ae 100644 --- a/libethereum/AccountDiff.h +++ b/libethereum/AccountDiff.h @@ -22,6 +22,7 @@ #pragma once #include +#include #include namespace dev @@ -29,47 +30,55 @@ namespace dev namespace eth { -enum class ExistDiff { Same, New, Dead }; -template -class Diff +/// Type of change that an account can have from state to state. +enum class AccountChange { -public: - Diff() {} - Diff(T _from, T _to): m_from(_from), m_to(_to) {} - - T const& from() const { return m_from; } - T const& to() const { return m_to; } - - explicit operator bool() const { return m_from != m_to; } - -private: - T m_from; - T m_to; + None, ///< Nothing changed at all. + Creation, ///< Account came into existance. + Deletion, ///< Account was deleted. + Intrinsic, ///< Account was already in existance and some internal aspect of the account altered such as balance, nonce or storage. + CodeStorage, ///< Account was already in existance and the code of the account changed. + All ///< Account was already in existance and all aspects of the account changed. }; -enum class AccountChange { None, Creation, Deletion, Intrinsic, CodeStorage, All }; +/// @returns a three-character code that expresses the type of change. +char const* lead(AccountChange _c); +/** + * @brief Stores the difference between two accounts (typically the same account at two times). + * + * In order to determine what about an account has altered, this struct can be used to specify + * alterations. Use changed() and changeType() to determine what, if anything, is different. + * + * Five members are accessible: to determine the nature of the changes. + */ struct AccountDiff { + /// @returns true if the account has changed at all. inline bool changed() const { return storage.size() || code || nonce || balance || exist; } - char const* lead() const; + /// @returns a three-character code that expresses the change. AccountChange changeType() const; - Diff exist; - Diff balance; - Diff nonce; - std::map> storage; - Diff code; + Diff exist; ///< The account's existance; was it created/deleted or not? + Diff balance; ///< The account's balance; did it alter? + Diff nonce; ///< The account's nonce; did it alter? + std::map> storage; ///< The account's storage addresses; each has its own Diff. + Diff code; ///< The account's code; in general this should only have changed if exist also changed. }; +/** + * @brief Stores the difference between two states; this is just their encumbent accounts. + */ struct StateDiff { - std::map accounts; + std::map accounts; ///< The state's account changes; each has its own AccountDiff. }; } +/// Simple stream output for the StateDiff. std::ostream& operator<<(std::ostream& _out, dev::eth::StateDiff const& _s); +/// Simple stream output for the AccountDiff. std::ostream& operator<<(std::ostream& _out, dev::eth::AccountDiff const& _s); }