

//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
//_/_/
//_/_/  This file is part of CMSDK version 2.1.1.260726 (26 July 2026)
//_/_/  
//_/_/  developed by
//_/_/  
//_/_/  Communicative Machines Ltd. 
//_/_/    http://cmlabs.com/
//_/_/  Copyright (c) 2026
//_/_/  
//_/_/  in collaboration with 
//_/_/  
//_/_/  Icelandic Institute for Intelligent Machines ses
//_/_/    Menntavegur 1
//_/_/    101 Reykjavik
//_/_/    ICELAND
//_/_/    http://www.iiim.is/
//_/_/
//_/_/  and is released under the following
//_/_/  
//_/_/  EXTENDED BSD License
//_/_/
//_/_/  Redistribution and use in source and binary forms, with or without
//_/_/  modification, is permitted provided that the following conditions 
//_/_/  are met:
//_/_/
//_/_/  - Redistributions of source code must retain the above copyright 
//_/_/    and collaboration notice, this list of conditions and the following 
//_/_/    disclaimer.
//_/_/
//_/_/  - Redistributions in binary form must reproduce the above copyright 
//_/_/    notice, this list of conditions and the following disclaimer in the 
//_/_/    documentation and/or other materials provided with the distribution.
//_/_/
//_/_/  - Neither the name of its copyright holders nor the names of its 
//_/_/    contributors may be used to endorse or promote products derived from 
//_/_/    this software without specific prior written permission.
//_/_/
//_/_/  - CADIA Clause: The license granted in and to the software under this 
//_/_/    agreement is a limited-use license. The software may not be used in 
//_/_/    furtherance of: (i) intentionally causing bodily injury or severe 
//_/_/    emotional harm to any person; (ii) invading the personal privacy or 
//_/_/    violating the human rights of any person; or (iii) committing or 
//_/_/    preparing for any act of war. 
//_/_/
//_/_/  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
//_/_/  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
//_/_/  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 
//_/_/  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 
//_/_/  OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
//_/_/  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
//_/_/  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
//_/_/  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
//_/_/  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
//_/_/  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
//_/_/  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//_/_/
//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
/*! @file MemoryRequestQueues.h
    @brief Static algorithms for request queues and the request-status map used by the shared-memory request/reply server.
    @ingroup Memory

    Provides the raw building blocks for MemoryRequestServer/MemoryRequestConnection:
    circular DataMessage queues (RequestQueueHeader) and a bitfield-indexed request-status
    table (RequestStatusHeader/RequestStatusEntry) that tracks each request through the
    MEMORYREQUEST_* lifecycle. All functions operate on raw mapped addresses; callers
    coordinate locking.

    @warning Shared-memory layouts; changing any struct here requires a full rebuild of
    all binaries (`make clean && make`) — see MemoryManager.h for the ABI warning. */

#if !defined(_MEMORYREQUESTQUEUES_H_)
#define _MEMORYREQUESTQUEUES_H_

#include "PsyTime.h"
#include "DataMessage.h"

namespace cmlabs {

/*! @name Request lifecycle status values for the request server (RequestStatusEntry::status)
    @{ */
#define MEMORYREQUEST_ERROR			0	/*!< Error/invalid. */
#define MEMORYREQUEST_IDLE			1	/*!< Slot unused. */
#define MEMORYREQUEST_INIT			2	/*!< Request being composed. */
#define MEMORYREQUEST_SUBMITTED		3	/*!< Placed on the server's queue. */
#define MEMORYREQUEST_RECEIVED		4	/*!< Dequeued by the server. */
#define MEMORYREQUEST_STARTED		5	/*!< Processing started. */
#define MEMORYREQUEST_COMPLETED		6	/*!< Processing finished. */
#define MEMORYREQUEST_REPLIED		7	/*!< Reply enqueued to the requester. */
#define MEMORYREQUEST_REPLYRECEIVED	8	/*!< Requester consumed the reply. */
#define MEMORYREQUEST_FINISHED		9	/*!< Transaction closed; slot reclaimable. */
/*! @} */

/*! @brief Header of one circular request queue; followed by serialized DataMessages between startPos and endPos.
    @warning Shared-memory layout; see MemoryManager.h for the ABI/rebuild warning. */
struct RequestQueueHeader {
	uint32 size;
	uint32 count;
	uint64 createdTime;
	uint64 lastUpdateTime;
	uint16 status;
	uint32 startPos;
	uint32 endPos;
	uint32 padding;
	// N x DataMessages from startPos to endPos
};



/*! @brief Header of the request-status table; followed by a bitfield and countTotal RequestStatusEntry records.
    @warning Shared-memory layout; see MemoryManager.h for the ABI/rebuild warning. */
struct RequestStatusHeader {
	uint32 size;
	uint32 countTotal;
	uint32 countInUse;
	uint64 createdTime;
	uint64 lastUpdateTime;
	uint16 status;
	uint32 bitFieldSize;
	// Bitfield
	// countTotal x Entries
};

/*! @brief One request transaction's status record.
    @warning Shared-memory layout; see MemoryManager.h for the ABI/rebuild warning. */
struct RequestStatusEntry {
	uint64 id;
	uint64 createdTime;
	uint64 lastUpdateTime;
	uint16 status;
	uint32 from; // id of connection making the request
	uint32 to; // id of connection processing the request
};

/*! @brief Static helpers for request queues and the request-status map (raw shared memory).
    @ingroup Memory
    Init* lays out a fresh region, Check* validates an existing one; queue functions copy
    DataMessages in/out (returned messages are caller-owned heap copies). Callers must
    provide external synchronisation (the request server/connection mutexes). */
class MemoryRequestQueues {
public:
	static bool InitQueue(char* data, uint32 size);			/*!< Initialise a queue region of @a size bytes. @return true on success. */
	static bool CheckQueue(char* data, uint32 size);		/*!< Validate an existing queue region. @return true if consistent. */
	static bool AddToQueue(char* data, DataMessage* msg);	/*!< Append a copy of @a msg (caller keeps ownership). @return true on success. */
	static DataMessage* GetNextQueueMessage(char* data);	/*!< Pop the next message. @return Caller-owned copy or NULL if empty. */

	static bool InitRequestMap(char* data, uint32 count);	/*!< Initialise a status map for @a count requests. @return true on success. */
	static bool CheckRequestMap(char* data, uint32 count);	/*!< Validate an existing status map. @return true if consistent. */
	static uint64 AddNewRequest(char* data, uint16 status, uint32 from, uint32 to);	/*!< Allocate a request slot. @return New request id, 0 on failure. */
	static bool SetRequestStatus(char* data, uint64 id, uint16 status);				/*!< Advance a request's MEMORYREQUEST_* status. @return true on success. */
	static uint32 GetRequestStatus(char* data, uint64 id, uint64& createdTime, uint64& lastUpdateTime);	/*!< @return Status plus timestamps via out-params. */
	static bool CloseRequest(char* data, uint64 id);		/*!< Release the request slot. @return true on success. */
private:
	static RequestStatusEntry* GetRequestEntry(char* data, uint64 id);	/*!< @return Entry for @a id or NULL (pointer into shared memory). */
};

} // namespace cmlabs

#endif //_MEMORYREQUESTQUEUES_H_

