CTR Pia  4.11.3
Game Communication Engine
clone_AtomicSharingClone.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: clone_AtomicSharingClone.h
4 
5  Copyright Nintendo. All rights reserved.
6 
7  These coded instructions, statements, and computer programs contain
8  proprietary information of Nintendo of America Inc. and/or Nintendo
9  Company Ltd., and are protected by Federal copyright law. They may
10  not be disclosed to third parties or copied or duplicated in any form,
11  in whole or in part, without the prior written consent of Nintendo.
12  *---------------------------------------------------------------------------*/
13 
14 
15 #pragma once
16 
17 #include <pia/clone/clone_definitions.h>
18 #include <pia/clone/clone_SharingClone.h>
19 
20 namespace nn
21 {
22 namespace pia
23 {
24 namespace clone
25 {
26 
27 
28 /*!
29 @brief This class is a derivative of <tt>CloneBase</tt> and provides functionality for exclusively controlling the lock on sending and for bidirectional sending and receiving.
30 
31 @date 2013-09-25 Initial version.
32 */
34 {
35 public:
36 /*!
37 @brief Instantiates the object with default parameters (default constructor).
38 */
40 
41 
42 /*!
43 @brief Destroys the object (destructor).
44 */
45  virtual ~AtomicSharingClone();
46 
47 
48 /*!
49 @brief Attempts to acquire a lock on sending.
50 @details If this function is called while the state is <tt>@ref LOCK_STATUS_UNLOCKED</tt>, the state transitions to <tt>@ref LOCK_STATUS_TRY_LOCK</tt>.
51 If the lock successfully acquired, the state changes to <tt>@ref LOCK_STATUS_LOCKED</tt>.
52 If the lock cannot be acquired because another station has them, the state changes to <tt>@ref LOCK_STATUS_UNLOCKED</tt>.
53 This function does nothing if called while the state is <tt>@ref LOCK_STATUS_TRY_LOCK</tt> or <tt>@ref LOCK_STATUS_LOCKED</tt>.
54 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.
55 @retval ResultInvalidState Indicates that the object is not active. (<tt>IsActive</tt> returns <tt>false</tt>. ) Programming error. Fix your program so that this error is not returned.
56 */
57  nn::Result TryLock();
58 
59 
60 /*!
61 @brief Releases the send lock.
62 @details If this function is called while the state is <tt>@ref LOCK_STATUS_LOCKED</tt>, the state transitions to <tt>@ref LOCK_STATUS_UNLOCKED</tt> and other stations can acquire the lock.
63 If called while the state is <tt>@ref LOCK_STATUS_TRY_LOCK</tt>, the object stops trying to acquire a lock and the state changes to <tt>@ref LOCK_STATUS_UNLOCKED</tt>.
64 This function does nothing if it is called while the state is <tt>@ref LOCK_STATUS_UNLOCKED</tt>.
65 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.
66 @retval ResultInvalidState Indicates that the object is not active. (<tt>IsActive</tt> returns <tt>false</tt>. ) Programming error. Fix your program so that this error is not returned.
67 */
68  nn::Result Unlock();
69 
70 
71 /*!
72 @brief Enumerates the status of the lock.
73 */
75  {
76  LOCK_STATUS_UNLOCKED = 0x10, //!< Specifies that the station does not have the lock.
77  LOCK_STATUS_TRY_LOCK = 0x20, //!< Specifies that the station is attempting to acquire the lock.
78  LOCK_STATUS_LOCKED = 0x30 //!< Specifies that the station has the lock.
79  };
80 
81 
82 /*!
83 @brief Gets the status of the lock.
84 @return Returns the status of the lock.
85 */
87  {
88  return static_cast<LockStatus>(m_LockStatus & cLockStatusMask);
89  }
90 
91 
92 /*!
93 @brief Prints information that is useful for debugging.
94 
95 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
96 */
97  virtual void Trace(u64 flag) const;
98 
99 
100  //! @cond PRIVATE
101 
102 protected:
103  virtual void OnStartup();
104  virtual void OnCleanup();
105  virtual void OnEnd();
106 
107  virtual void OnExit(StationIndex stationId);
108  virtual void OnDisconnect(StationIndex stationId, bool isValid);
109 
110  virtual void OnAddParticipant(StationIndex stationIndex);
111 
112 public:
113  virtual void ReceiveReject(StationIndex src, ClockValue clock);
114  virtual void ReceiveStop(StationIndex src);
115 
116  enum LockResult
117  {
118  LOCK_RESULT_OK,
119  LOCK_RESULT_NG,
120  LOCK_RESULT_DEFER
121  };
122 
123  LockResult ReceiveTryLock(StationIndex src, ClockValue clock, u32 participantBitmap);
124  void ReceiveLockOK(StationIndex src, ClockValue clock, u8 count, u32 participantBitmap);
125  void ReceiveLockNG(StationIndex src, ClockValue clock);
126 
127 public:
128  static Type GetTypeStatic()
129  {
130  return TYPE_ATOMIC;
131  }
132  static Key ToKey(Id id)
133  {
134  return CloneBase::ToKey(TYPE_ATOMIC, STATION_INDEX_INVALID, id);
135  }
136  virtual Type GetTypeVirtual() const
137  {
138  return GetTypeStatic();
139  }
140 
141 public:
142  class LockCommandToken : public ClockCommandToken
143  {
144  public:
145  explicit LockCommandToken(AtomicSharingClone* pClone)
146  : ClockCommandToken(pClone), m_DestBitmap(0)
147  {
148  }
149  virtual CommandType GetType() const
150  {
151  return COMMAND_LOCK;
152  }
153  virtual u32 GetDestStationBitmap() const
154  {
155  return m_DestBitmap;
156  }
157  virtual bool IsUnicast() const
158  {
159  return true;
160  }
161  void SetDestBitmap(u32 destBitmap)
162  {
163  PIA_TRACE_EX(common::TRACE_FLAG_CLONE, "called LockCommandToken key:0x%016llx state:%d dest:0x%08x -> 0x%08x", GetClone() != NULL ? GetClone()->GetKey() : 0, GetClone() != NULL ? GetClone()->GetState() : 0, m_DestBitmap, destBitmap);
164  m_DestBitmap = destBitmap;
165  }
166  void Exit(StationIndex stationId)
167  {
168  PIA_TRACE_EX(common::TRACE_FLAG_CLONE, "called LockCommandToken key:0x%016llx state:%d dest:0x%08x -> 0x%08x", GetClone() != NULL ? GetClone()->GetKey() : 0, GetClone() != NULL ? GetClone()->GetState() : 0, m_DestBitmap, m_DestBitmap & ~(0x1 << stationId));
169  m_DestBitmap &= ~(0x1 << stationId);
170  }
171  virtual ClockValue GetClock() const
172  {
173  return static_cast<const AtomicSharingClone*>(GetClone())->m_LockClock;
174  }
175 
176  private:
177  ClockValue m_DestBitmap;
178  };
179 
180  virtual bool IsReadyToSetValue() const;
181 
182 private:
183  enum InnerLockStatus
184  {
185  eILUnlocked = LOCK_STATUS_UNLOCKED | 0x1,
186  eILKeepLock = LOCK_STATUS_UNLOCKED | 0x2,
187  eILTryLock = LOCK_STATUS_TRY_LOCK | 0x1,
188  eILLocked = LOCK_STATUS_LOCKED | 0x1
189  };
190 
191  enum
192  {
193  cLockStatusMask = 0xf0
194  };
195 
196  InnerLockStatus m_LockStatus;
197  ClockValue m_LockClock;
198  ClockValue m_UnlockClock;
199 
200  LockCommandToken m_LockCommandToken;
201 
202 public:
203  template <int TEST_ID, typename Arg>
204  static void Test(const AtomicSharingClone& obj, Arg* pArg = NULL);
205 
206  //! @endcond
207 };
208 }
209 }
210 } // end of namespace nn::pia::clone
u32 ClockValue
Defines a type that holds a clock value.
Definition: clone_definitions.h:44
This class is a derivative of CloneBase and provides functionality for bidirectional sending and rece...
Definition: clone_SharingClone.h:34
StationIndex
Enumerates StationIndex values.
Definition: platformCtr.h:44
Definition: assert.h:115
ID indicating a station that is not present in the session.
Definition: platformCtr.h:59
virtual ~AtomicSharingClone()
Destroys the object (destructor).
LockStatus GetLockStatus() const
Gets the status of the lock.
Definition: clone_AtomicSharingClone.h:86
LockStatus
Enumerates the status of the lock.
Definition: clone_AtomicSharingClone.h:74
nn::Result TryLock()
Attempts to acquire a lock on sending.
Specifies that the station is attempting to acquire the lock.
Definition: clone_AtomicSharingClone.h:77
nn::Result Unlock()
Releases the send lock.
AtomicSharingClone()
Instantiates the object with default parameters (default constructor).
Specifies that the station does not have the lock.
Definition: clone_AtomicSharingClone.h:76
virtual void Trace(u64 flag) const
Prints information that is useful for debugging.
static const TraceFlag TRACE_FLAG_CLONE
Flag for tracing the PiaClone module.
Definition: common_Trace.h:174
u32 Id
Specifies the type of the ID for identifying clones.
Definition: clone_CloneBase.h:68
This class is a derivative of CloneBase and provides functionality for exclusively controlling the lo...
Definition: clone_AtomicSharingClone.h:33
Specifies that the station has the lock.
Definition: clone_AtomicSharingClone.h:78