ryzom/server/src/entities_game_service/cdb_group.h

   1 // Ryzom - MMORPG Framework <http://dev.ryzom.com/projects/ryzom/>
   2 // Copyright (C) 2010  Winch Gate Property Limited
   3 //
   4 // This program is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU Affero General Public License as
   6 // published by the Free Software Foundation, either version 3 of the
   7 // License, or (at your option) any later version.
   8 //
   9 // This program is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU Affero General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU Affero General Public License
  15 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 #ifndef NL_CDB_GROUP_H
  18 #define NL_CDB_GROUP_H
  19
  20 #include "nel/misc/entity_id.h"
  21 #include "player_manager/cdb_synchronised.h"
  22 #include <set>
  23 #include "game_item_manager/guild_inv.h"
  24
  25
  26 class CCharacter;
  27 class IDataProvider;
  28
  29 typedef NLMISC::CEntityId CCDBRecipient;
  30
  31
  32 /**
  33  * Database group.
  34  *
  35  * A group type is identified by a TCDBBank enum.
  36  * One recipient CAN'T belong to several groups of the same bank (ex: one player can belong
  37  * to 0 or 1 guild).
  38  *
  39  * What are the main advantages of using a CCDBGroup instead of duplicating changes
  40  * on several character's databases?
  41  * - Less user code.
  42  * - The data are shared, and the change trackers are shared as well (less memory needed).
  43  * - The delta buffer is built only once per tick (less CPU).
  44  * - The delta buffer is sent in one message to a FS (less network traffic).
  45  * - The number of bits used to locate properties is lower, as there is one tree per bank (less
  46  * network traffic).
  47  *
  48  * How to use the database system?
  49  * Here is a tutorial, it explains how CCDBGroup is used in the EGS.
  50  *
  51  * A. Put a CCDBSynchronised database in the character class.
  52  *    Put a CCDBGroup in each group class (eg. in a guild class).
  53  *    Init them with the corresponding banks.
  54  *
  55  * B. At each game cycle, here is the using process:
  56  *
  57  * 1. To populate a CCDBGroup, use addRecipient()/removeRecipient(). addRecipient() will send to it all
  58  *    modifications in the group database since the beginning. removeRecipient() will ask the client to
  59  *    reset the corresponding data, so that a new addRecipient() would work (the delta values need be
  60  *    done with 0 as the reference value).
  61  *
  62  * 2. Your code sets some properties using Database.setProp(), either database of a particular character
  63  *    or the database in a CCDBGroup (in database.xml, the branch banks must have been set likewise).
  64  *
  65  * 3. Now you want to build a delta buffer for all characters, including modifications for groups and
  66  *    particular characters.
  67  *    Call sendDeltas() on each CCDBGroup object. You may provide maxBitSize to limit the space used by
  68  *    these groups. You need not call writeDelta() on the Database object in a CCDBGroup. A message will
  69  *    be emitted to all front-ends, to send the changes to all the recipients of the group.
  70  *
  71  * 4. Call writeDelta() on the CCDBSynchronised database of every character.
  72  *    You should provide maxBitSize to limit the size of the message.
  73  *    The recommended available size should be provided by the network emitting system (front-end service).
  74  *    Push the outbox bitmemstream of every character into an output message. You should differenciate the
  75  *    initial message with other updates so that the client can react differently (it will not call any
  76  *    observers for the initial message). Note: you can know the "not sent yet" flag in CCDBSynchronized
  77  *    database, using setAsSent()/notSentYet(). Send the message.
  78  *
  79  * \author Olivier Cado
  80  * \author Nevrax France
  81  * \date 2004
  82  */
  83 class CCDBGroup
  84 {
  85 public:
  86
  87         /// Flags for sendDeltas
  88         enum {
  89                 SendDeltasToRecipients          =       0,                      ///< If specified, send the deltas to the group's recipent list
  90                 SendDeltasToAll                         =       1,                      ///< If specified, send the deltas to everyong (broadcast), ignores the recipent list
  91         };
  92
  93         /// Init (the singleton of CCDBStructBanks must have been initialized before)
  94         void                            init( TCDBBank bank ) { Database.init( bank, true ); }
  95
  96         /**
  97          * Add a recipient.
  98          * - recipient must be ready for writing (e.g. at state 1 of above tutorial), because it will
  99          * be filled immediately with the modifications that occurred before its arrival.
 100          * //Obsolete:
 101          * //- recipient must neither move in memory nor be removed between calls of addRecipient() and
 102          * //removeRecipient(). Beware with vectors and reallocation.
 103          */
 104         void                            addRecipient( const CCDBRecipient& recipient );
 105
 106         /// Remove a recipient
 107         void                            removeRecipient( const CCDBRecipient& recipient );
 108
 109         /// Use Database to set properties
 110         CCDBSynchronised        Database;
 111
 112         /// Write and send the delta to all recipients, if there's something to write. Set maxBitSize to ~0 for no limit.
 113         /// @param[in] sendFlags A combination of Flags (see enum above) indicating how the deltas are to be sent
 114         void                            sendDeltas( uint32 maxBitSize, IDataProvider& dataProvider, uint8 sendFlags);
 115
 116         /// Simpler version
 117         /// @param[in] sendFlags A combination of Flags (see enum above) indicating how the deltas are to be sent
 118         void                            sendDeltas( uint32 maxBitSize, uint8 sendFlags)
 119         {
 120                 CFakeDataProvider dp;
 121                 sendDeltas( maxBitSize, dp, sendFlags );
 122         }
 123
 124
 125 private:
 126
 127         typedef std::set< CCDBRecipient > CRecipientList;
 128
 129         /// Recipients
 130         CRecipientList                                  _Recipients;
 131
 132         /// New recipients since the latest sendDeltas()
 133         std::vector< CCDBRecipient >    _NewRecipients;
 134 };
 135
 136
 137
 138 #endif // NL_CDB_GROUP_H
 139
 140 /* End of cdb_group.h */