// ==++==
// 
//   Copyright (c) Microsoft Corporation.  All rights reserved.
// 
// ==--==
/* -------------------------------------------------------------------------- *
 * Common Language Runtime Profiling interfaces
 *
 * The IGCHost allows a host environment to get statistics about the
 * garbage collector as well as to gain some limited control over collections.
 * This interface can be QueryInterface'd for on from the CorHost object.
 * -------------------------------------------------------------------------- */

import "unknwn.idl";

typedef enum
{
    COR_GC_COUNTS                 = 0x00000001,         // Fill out count values.
    COR_GC_MEMORYUSAGE            = 0x00000002,         // Fill out memory usage values.
} COR_GC_STAT_TYPES;

typedef enum
{
    COR_GC_THREAD_HAS_PROMOTED_BYTES  = 0x00000001      // Thread has bytes promoted in the last GC
                                                        // if flags set to this value.
} COR_GC_THREAD_STATS_TYPES;


/*
 * This structure is used to return statics for the GC system.  Set the Flags
 * value to a bitmask of values that should be returned.  Only those values which
 * are requested are calculated and returned to the caller.
 */
typedef struct _COR_GC_STATS
{
    ULONG       Flags;                                  // What values to get.

    // Value when COR_GC_COUNTS is specified.
    SIZE_T       ExplicitGCCount;                        // How many times was GC forced to run by external request.
    SIZE_T       GenCollectionsTaken[3];                    // Number of collections done for each generation

    // Memory sizes, valid for COR_GC_MEMORYUSAGE.
    SIZE_T       CommittedKBytes;                        // Total committed bytes from all heaps.    
    SIZE_T       ReservedKBytes;                         // Total reserved bytes from all heaps.    
    SIZE_T       Gen0HeapSizeKBytes;                     // Size of gen 0 heap.
    SIZE_T       Gen1HeapSizeKBytes;                     // Size of gen 1 heap.
    SIZE_T       Gen2HeapSizeKBytes;                     // Size of gen 2 heap.
    SIZE_T       LargeObjectHeapSizeKBytes;              // Size of large object heap.
    SIZE_T       KBytesPromotedFromGen0;                 // How many bytes promoted to next generation.
    SIZE_T       KBytesPromotedFromGen1;

} COR_GC_STATS;

/*
 * This structure is used to return per-thread statistics related to GC.
 */
typedef struct _COR_GC_THREAD_STATS
{
    ULONGLONG   PerThreadAllocation;                    // Amount of memory allocated on this
                                                        // thread.  Cleared to 0 on each Gen 0 collection.
    ULONG       Flags;                                  // Thread has bytes promoted in the last GC?
} COR_GC_THREAD_STATS;



/*
 * This interface is used to get information about the GC system and
 * control some aspects of the GC.  This interface is for expert usage
 * only, and can severely impact the performance of an application if
 * used improperly!!
 */
[
	object,
	uuid(FAC34F6E-0DCD-47b5-8021-531BC5ECCA63),
	pointer_default(unique),
	local
]
interface IGCHost : IUnknown
{
    /*
     * Sets the segment size and gen 0 maximum size.  This value may only be
     * specified once and will not change if called later.
     */
    HRESULT SetGCStartupLimits([in] DWORD SegmentSize, [in] DWORD MaxGen0Size);
    
    /*
     * Forces a collection to occur for the given generation, regardless of
     * current GC statistics.  A value of -1 means collect all generations.
     */
    HRESULT Collect([in] LONG Generation);
    
    /*
     * Returns a set of current statistics about the state of the GC system.
     * These values can then be used by a smart allocation system to help the
     * GC run, by say adding more memory or forcing a collection.
     */
    HRESULT GetStats([in][out] COR_GC_STATS *pStats);
    
    /*
     * This method returns the per-thread statics gathered by the GC. 
     */
    HRESULT GetThreadStats([in] DWORD *pFiberCookie, [in][out] COR_GC_THREAD_STATS *pStats);
    
    /*
     * This method allows the caller to set virtual memory limit (MB) of the runtime. This limit
     * can be changed dynamically.
     */
    HRESULT SetVirtualMemLimit ([in] SIZE_T sztMaxVirtualMemMB);
}


