/* 
 * (c) Copyright 2003-2024, Real-Time Innovations, Inc. All rights reserved.
 * 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 advlog_context_h
#define advlog_context_h

#ifndef osapi_activityContext_h
  #include "osapi/osapi_activityContext.h"
#endif

#include "advlog/advlog_dll.h"

#ifndef reda_worker_h
  #include "reda/reda_worker.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

/*e \ingroup ADVLOGContext
 * @brief Activity IDs are defined as 32 bit integers.
 */
typedef RTI_UINT32 ADVLOGActivityID;

/*e \ingroup ADVLOGContext
 * @brief The template relate an Id to each format.
 */
struct ADVLOGContextTemplate {
    ADVLOGActivityID activityId;  /* ID# for the activity */
    const char *format;    /* format of the activity string */
};

/* ========================================= */
/*  ContextScope                             */
/* ========================================= */

/*
 * We define "scope" as a block of code which:
 *  - Starts with a ADVLOGContextScope_begin call. This macro
 *  opens the block and initializes all the stack variables needed to support
 *  entering/leaving contexts within the block.
 *  - Keeps track of the context entries we enter and leave. To do so:
 *      - Within the scope, we can enter a new context entry using the following
 *          macros:
 *          - ADVLOGContextScope_enterActivity
 *          - ADVLOGContextScope_enterResource
 *          - ADVLOGContextScope_enterActivityWithParams
 *          - ADVLOGContextScope_enterResourceWithParams
 *          - ADVLOGContextScope_enterResourceGuidWithParams
 *      - Within the scope, we can leave a context entry using the following
 *          macro:
 *          - ADVLOGContextScope_leave
 *  - Ends with calling ADVLOGContextScope_end.
 *      Upon ending a scope, any remaining entered entries will leave.
 *
 * Additionally, some ContextScopes will support also "start".
 * Starting a scope consists of beginning the scope plus entering an entry.
 */

/*e \ingroup RTIOsapiActivityContext
 * @brief It is a macro which opens the scope and then initializes in the stack:
 *   - An index
 *   - A list of RTIOsapiActivityContextStackEntry.
 *  ADVLOGContextScope_beginWithEntries does not create a list of Params.
 * The ContextScope that this macro creates can contain calls to the following APIs:
 *      - ADVLOGContextScope_enterActivity
 *      - ADVLOGContextScope_enterResource
 *
 * @param maxEntryCount \b In. Size of the list of entries.
 */
extern ADVLOGDllExport
void ADVLOGContextScope_beginWithEntries(RTI_UINT32 maxEntryCount);

/*e \ingroup RTIOsapiActivityContext
 * @brief It is a macro which opens the scope and then initializes in the stack:
 *   - An index
 *   - A list of RTIOsapiActivityContextStackEntry
 *   - A list of params
 *   - A pointer to the position of the list of params
 * The ContextScope that this macro creates can contain calls to the following APIs:
 *      - ADVLOGContextScope_enterActivityWithParams
 *      - ADVLOGContextScope_enterResourceWithParams
 *      - ADVLOGContextScope_enterResourceGuidWithParams
 *
 * @param maxEntryCount \b In. Size of the list of entries.
 * @param maxParamsCount \b In. Size of the list of params.
 */
extern ADVLOGDllExport
void ADVLOGContextScope_beginWithEntriesAndParams(
        RTI_UINT32 maxEntryCount,
        RTI_UINT32 maxParamsCount);

/*e
 * \ingroup RTIOsapiActivityContext
 * @brief Enter an activity entry in the activity context.
 *  This macro uses the variables defined in the begin macro.
 *  In order to leave this entry from the context, you can call (either or
 * both):
 *      - ADVLOGContextScope_leave
 *      - ADVLOGContextScope_end
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 * @param formatTemplate \b In. The format of the entry.
 */
extern ADVLOGDllExport void ADVLOGContextScope_enterActivity(
        struct REDAWorker *worker,
        const struct ADVLOGContextTemplate *contextTemplate);

/*e
 * \ingroup RTIOsapiActivityContext
 * @brief Enter an activity entry in the activity context.
 *  This macro uses the variables defined in the begin macro.
 *  In order to leave this entry from the context, you can call (either or
 * both):
 *      - ADVLOGContextScope_leave
 *      - ADVLOGContextScope_end
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 * @param formatTemplate \b In. The format of the entry.
 * @param ... \b In. List of params.
 */
extern ADVLOGDllExport void ADVLOGContextScope_enterActivityWithParams(
        struct REDAWorker *worker,
        const struct ADVLOGContextTemplate *contextTemplate,
        ...);

/*e
 * \ingroup RTIOsapiActivityContext
 * @brief Enter a resource entry in the activity context.
 *  This macro uses the variables defined in the begin macro.
 *  In order to leave this entry from the context, you can call (either or
 * both):
 *      - ADVLOGContextScope_leave
 *      - ADVLOGContextScope_end
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 * @param formatTemplate \b In. The format of the entry.
 * @param resource \b In. The resource of the entry.
 */
extern ADVLOGDllExport void ADVLOGContextScope_enterResource(
        struct REDAWorker *worker,
        const char *resource);

/*e
 * \ingroup RTIOsapiActivityContext
 * @brief Enter a resource entry in the activity context.
 *  This macro uses the variables defined in the begin macro.
 *  In order to leave this entry from the context, you can call (either or
 * both):
 *      - ADVLOGContextScope_leave
 *      - ADVLOGContextScope_end
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 * @param formatTemplate \b In. The format of the entry.
 * @param ... \b In. List of params.
 */
extern ADVLOGDllExport void ADVLOGContextScope_enterResourceWithParams(
        struct REDAWorker *worker,
        const struct ADVLOGContextTemplate *contextTemplate,
        ...);

/*e
 * \ingroup RTIOsapiActivityContext
 * @brief Enter a resource with Guid entry in the activity context.
 *  This macro uses the variables defined in the begin macro.
 *  In order to leave this entry from the context, you can call (either or
 * both):
 *      - ADVLOGContextScope_leave
 *      - ADVLOGContextScope_end
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 * @param formatTemplate \b In. The format of the entry.
 * @param ... \b In. List of params.
 */
extern ADVLOGDllExport void ADVLOGContextScope_enterResourceGuidWithParams(
        struct REDAWorker *worker,
        const struct ADVLOGContextTemplate *contextTemplate,
        ...);

/*i
 * \ingroup RTIOsapiActivityContext
 * @brief Leave the last entry of the activity context.
 *  This macro uses some variables defined in begin macro.
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 */
extern ADVLOGDllExport void ADVLOGContextScope_leave(struct REDAWorker *worker);

/*i
 * \ingroup RTIOsapiActivityContext
 * @brief It is a macro which leaves all the entries of the activity context
 *   entered after calling the begin macro.
 * It closes the scope.
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 */
extern ADVLOGDllExport void ADVLOGContextScope_end(struct REDAWorker *worker);

/* ========================================= */
/*  Context enter and leave entries          */
/* ========================================= */

/*i
 * \ingroup RTIOsapiActivityContext
 * @brief Enter an entry in the activity context.
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 * @param entry \b In. The entry to enter.
 */
extern ADVLOGDllExport void ADVLOGContext_enter(
        struct REDAWorker *worker,
        struct RTIOsapiActivityContextStackEntry *entry);

/*i
 * \ingroup RTIOsapiActivityContext
 * @brief Enter two entries in the activity context. Useful because one of the
 * most common use cases is to enter a resource and an activity at the same
 * time.
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 * @param entry1 \b In. The entry1 to enter.
 * @param entry2 \b In. The entry1 to enter.
 */
extern ADVLOGDllExport void ADVLOGContext_enterPair(
        struct REDAWorker *worker,
        struct RTIOsapiActivityContextStackEntry *entry1,
        struct RTIOsapiActivityContextStackEntry *entry2);

/*i
 * \ingroup RTIOsapiActivityContext
 * @brief Leave the last entry of the activity context.
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 */
extern ADVLOGDllExport void ADVLOGContext_leave(struct REDAWorker *worker);

/*i
 * \ingroup RTIOsapiActivityContext
 * @brief Leave the last N entries of the activity context.
 *
 * @param worker \b In. If not null, we retrieve the activityContext through the
 * worker. If null, we retrieve the activityContext through thread specific
 * storage (TSS). Accessing the TSS has an impact on performance. Therefore, we
 * should pass the worker whenever we use the activity context in the critical
 * path.
 * @param groupSize \b In. The number of entries to leave from the context.
 */
extern ADVLOGDllExport void ADVLOGContext_leaveGroup(
        struct REDAWorker *worker,
        RTI_UINT32 groupSize);

/* ========================================= */
/*  Context templates                        */
/* ========================================= */

/*i \ingroup RTIOsapiActivityContext
 *  Template format for resource.
 */
extern ADVLOGDllVariable
const struct ADVLOGContextTemplate RTI_ADVLOG_CONTEXT_TEMPLATE_RESOURCE_s;

/*i \ingroup RTIOsapiActivityContext
 *  Template format for resource with topic, type, kind and domain.
 */
extern ADVLOGDllVariable
const struct ADVLOGContextTemplate
        RTI_ADVLOG_CONTEXT_TEMPLATE_RESOURCE_TO_TY_KI_DO_ssssd;

/*i \ingroup RTIOsapiActivityContext
 *  Template format for guid resource.
 */
extern ADVLOGDllVariable
const struct ADVLOGContextTemplate RTI_ADVLOG_CONTEXT_TEMPLATE_GUID_g;

/*i \ingroup RTIOsapiActivityContext
 *  Template format for guid resource with domain.
 */
extern ADVLOGDllVariable
const struct ADVLOGContextTemplate RTI_ADVLOG_CONTEXT_TEMPLATE_GUID_DO_gd;

/*i \ingroup RTIOsapiActivityContext
 *  Template format for guid resource with entityName and domain.
 */
extern ADVLOGDllVariable
const struct ADVLOGContextTemplate RTI_ADVLOG_CONTEXT_TEMPLATE_GUID_NA_DO_gsd;

/*i \ingroup RTIOsapiActivityContext
 *  Template format for guid resource with kind and domain.
 */
extern ADVLOGDllVariable
const struct ADVLOGContextTemplate RTI_ADVLOG_CONTEXT_TEMPLATE_GUID_KI_DO_gsd;

/*i \ingroup RTIOsapiActivityContext
 *  Template format topic resource with kind.
 */
extern ADVLOGDllVariable
const struct ADVLOGContextTemplate RTI_ADVLOG_CONTEXT_TEMPLATE_TOPIC_KI_s;

/*i \ingroup RTIOsapiActivityContext
 *  Template format for guid resource with kind, topic, type and domain.
 */
extern ADVLOGDllVariable
const struct ADVLOGContextTemplate
        RTI_ADVLOG_CONTEXT_TEMPLATE_GUID_KI_TO_TY_DO_gsssd;

/*i \ingroup RTIOsapiActivityContext
 *  Template format for guid resource with topic, type and domain.
 */
extern ADVLOGDllVariable
const struct ADVLOGContextTemplate
        RTI_ADVLOG_CONTEXT_TEMPLATE_GUID_TO_TY_KI_DO_gssd;

/*i \ingroup RTIOsapiActivityContext
 *  Template format for receive code path with the local Guid, the message kind
 *  and the remote Guid.
 */
extern ADVLOGDllVariable
const struct ADVLOGContextTemplate
        RTI_ADVLOG_CONTEXT_TEMPLATE_GUID_KI_ID_RECEIVE_gsg;

/*i \ingroup RTIOsapiActivityContext
 * Abbreviation to identify the entity kind.
 */
#define ADVLOG_ENTITY_SHORTNAME_PARTICIPANT "DP"
#define ADVLOG_ENTITY_SHORTNAME_PUBLISHER "Pu"
#define ADVLOG_ENTITY_SHORTNAME_SUBSCRIBER "Su"
#define ADVLOG_ENTITY_SHORTNAME_DATAWRITER "DW"
#define ADVLOG_ENTITY_SHORTNAME_DATAREADER "DR"

#define ADVLOG_ENTITY_NAME_TOPIC "Topic"


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

#include "advlog/advlog_context_impl.h"


#endif /* advlog_context_h */