/*
 * (c) Copyright, Real-Time Innovations, 2002-2024.
 * All rights reserved.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef event_activeDatabase_h
#define event_activeDatabase_h


#ifndef reda_database_h
  #include "reda/reda_database.h"
#endif
#ifndef event_dll_h
  #include "event/event_dll.h"
#endif
#ifndef event_activeObject_h
  #include "event/event_activeObject.h"
#endif
#ifndef event_smartTimer_h
  #include "event/event_smartTimer.h"
#endif
#ifndef osapi_threadFactory_h
  #include "osapi/osapi_threadFactory.h"
#endif

#ifdef __cplusplus
    extern "C" {
#endif

struct RTIEventActiveDatabase;

struct RTIEventTimer;

/*e \file 
    \brief Database with reaper thread
*/
     
/*e \defgroup RTIEventActiveDatabaseClass RTIEventActiveDatabase
    \ingroup RTIEventActiveObjectClass
    \brief An implementation of RTIEventActiveObject, and a derived class of
    REDADatabase, with *1* reaper thread for periodic clean up.

    The reaper thread may be woken up earlier too if smart timer is available
    on the platform.

    @note Opaque class
*/


/*e \defgroup RTIEventActiveDatabasePropertyClass RTIEventActiveDatabaseProperty
  \ingroup RTIEventActiveDatabaseClass
*/

/*e \ingroup RTIEventActiveDatabasePropertyClass
  \brief public member fields
*/
struct RTIEventActiveDatabaseProperty {
    /*e This class is a child of REDADatabase */
    struct REDADatabaseProperty parent;
    /*e And this object is active */
    struct RTIEventActiveObjectProperty active;
    /*e Garbage collection period
      @todo consider spliting into slow and fast period
    */
    struct RTINtpTime cleanupPeriod;
    /*e @brief The thread participant identification.
     Used to give a meaningful name to the thread.
    */
    char threadParticipantId[RTI_OSAPI_THREAD_PARTICIPANT_ID_MAX_SIZE];
};


/*e \ingroup RTIEventActiveDatabasePropertyClass
  \brief Use this initialize variable on the stack

  Default garbage collection period: 30 sec
*/
#define RTI_EVENT_ACTIVE_DATABASE_PROPERTY_DEFAULT { \
    REDA_DATABASE_PROPERTY_DEFAULT,                  \
    RTI_EVENT_ACTIVE_OBJECT_PROPERTY_DEFAULT,        \
    {30, 0},                                         \
    "#####", /* threadParticipantId */ \
}

struct RTIEventActiveDatabaseListener;/*forward declare */

/*e \ingroup RTIEventActiveDatabaseClass
  \brief dtor
  @pre database in RTI_EVENT_ACTIVE_OBJECT_STATE_STOPPED
  @param me \b In. Must be RTIEventActiveDatabase cached from
  RTIEventActiveDatabase_new.
  @param worker \b In. The identity of "thread" that is deleting the database.
  @return RTI_TRUE on successful deletion or RTI_FALSE on failure
  @mtsafety <<delete>>
*/
extern RTIEventDllExport RTIBool
RTIEventActiveDatabase_delete(struct RTIEventActiveDatabase *me,
                              struct REDAWorker *worker);

/*e \ingroup RTIEventActiveDatabaseClass
  \brief begin shutdown sequence

  @pre In state RTI_EVENT_ACTIVE_OBJECT_STATE_RUNNING
  @post In state RTI_EVENT_ACTIVE_OBJECT_STATE_SHUTDOWN
  @param me \b In. Must be RTIEventActiveDatabase cached from
  RTIEventActiveDatabase_new.
  @param worker \b In. The identity of "thread" that is shutting down the
  database.
  @return RTI_TRUE on success
  @mtsafety <<shutdown>>
*/
extern RTIEventDllExport RTIBool
RTIEventActiveDatabase_shutdown(struct RTIEventActiveDatabase *me,
				struct REDAWorker *worker);

/*e \defgroup RTIEventActiveDatabaseListenerClass RTIEventActiveDatabaseListener
  \ingroup RTIEventActiveDatabaseClass
  \brief Implement this interface to be notified of active database state
  changes.
*/

/*e \ingroup RTIEventActiveDatabaseListenerClass
  \brief called when the active database is fully operational.
  That is, you may not use an active database until this callback is called.

  @pre database in RTI_EVENT_ACTIVE_OBJECT_STATE_RUNNING
  @mtsafety <<singleThread>>
*/
typedef void (*RTIEventActiveDatabaseOnStartedCallback)(
    struct RTIEventActiveDatabase *database, void *onStartedParam,
    struct REDAWorker *worker);

/*e \ingroup RTIEventActiveDatabaseListenerClass
  \brief called when the active database wakes up periodically, typically to
  perform cleanup.  You can have the Active DB thread perform other DB-ish
  work, like cleaning up stale sample in the presentation layer.

  @pre database in RTI_EVENT_ACTIVE_OBJECT_STATE_RUNNING
  @mtsafety <<singleThread>>
*/
typedef void (*RTIEventActiveDatabaseOnWakeupCallback)(
    const struct RTIEventActiveDatabaseListener* me,
    struct REDAWorker *worker);

/*e \ingroup RTIEventActiveDatabaseListenerClass
  \brief Child of RTIEventActiveObjectListener
*/
struct RTIEventActiveDatabaseListener {
    /*e Parent is the first member */
    struct RTIEventActiveObjectListener parent;
    /*e Active database start-up is asynchronous, so use this method
      to learn when the active database is fully operational.
    */
    RTIEventActiveDatabaseOnStartedCallback onStarted;
    /*e Associated with the onStarted() method */
    void *onStartedParam;

    RTIEventActiveDatabaseOnWakeupCallback onWakeup;
};


#define RTI_EVENT_ACTIVE_DATABASE_LISTENER_DEFAULT { \
    RTI_EVENT_ACTIVE_OBJECT_LISTENER_DEFAULT, \
    NULL, NULL, NULL }

/*e \ingroup RTIEventActiveDatabaseClass
  \brief ctor
  @post active database in REDA_ACTIVE_OBJECT_STATE_STARTING
  @param workerFactory \b In.
  @param adminEA \b In.
  @param timer \b In. Event timer.
  @param listener \b In. Listener to listen to database events.
  Cannot be NULL.
  @param property \b In. <<valueType>>
  Contains optional detailed configuration
  properties for the database. If NULL is passed, defaults are used.
  @param worker \b In.
  @param threadFactory \b In. The thread factory to create threads. 
  @mtsafety <<new>>
*/
extern RTIEventDllExport struct RTIEventActiveDatabase *
RTIEventActiveDatabase_new(
    struct REDAWorkerFactory *workerFactory,
    struct REDAExclusiveArea *adminEA,
    struct RTIEventTimer *timer,
    const struct RTIEventActiveDatabaseListener *listener,
    const struct RTIEventActiveDatabaseProperty *property,
    struct RTIOsapiThreadFactory *threadFactory,
    struct REDAWorker *worker);

/*e \ingroup RTIEventActiveDatabaseClass
  \brief Fill in the given property with the state of this database as
  it was specified at creation time.
  
  @pre All pointers must be valid.
  @param property \b In. <<valueType>>
  @param worker \b In.
  @mtsafety safe.
*/
extern RTIEventDllExport void
RTIEventActiveDatabase_getProperty(
    struct RTIEventActiveDatabase *me,
    struct RTIEventActiveDatabaseProperty *property,
    struct REDAWorker *worker);

/*e \ingroup RTIEventActiveDatabaseClass
  \brief Force premature wakeup if using smart timer, so that garbage
  collection can be performed now instead of having to wait until the
  next wakeup time.
  @mtsafety <<multiThreadSafe>>
*/
extern RTIEventDllExport RTIBool
RTIEventActiveDatabase_wakeup(struct RTIEventActiveDatabase *me);

/*e \ingroup RTIEventActiveDatabaseClass
  \brief I wish I had polymorphism, but since this is C, use this to
  invoke methods of the parent.
*/
extern RTIEventDllExport
struct REDADatabase *
RTIEventActiveDatabase_getParent(struct RTIEventActiveDatabase *me);


#ifdef __cplusplus
    }	/* extern "C" */
#endif

#include "event/event_activeDatabase_impl.h"

#endif /* event_activeDatabase_h */