RTX64_MONITOR_CONTROL_OP

RTX64_MONITOR_CONTROL_OP is an enumeration that specifies a set of control operations to control monitoring within a RTSS application.

Syntax

typedef enum _RTX64_MONITOR_CONTROL_OP {
   MONITOR_CONTROL_RESERVED = 0,
   MONITOR_CONTROL_START,
   MONITOR_CONTROL_PAUSE,
   MONITOR_CONTROL_RESUME,
   MONITOR_CONTROL_STOP,
   MONITOR_CONTROL_ENABLE_EVENTS,
   MONITOR_CONTROL_DISABLE_EVENTS,
   MONITOR_CONTROL_SET_EVENT_TRIGGERS,
   MONITOR_CONTROL_RESET_EVENT_TRIGGERS,
   MONITOR_CONTROL_SET_CUSTOM_EVENT_TRIGGERS,
   MONITOR_CONTROL_RESET_CUSTOM_EVENT_TRIGGERS,
   MONITOR_CONTROL_ENABLE_COMPONENTS,
   MONITOR_CONTROL_GET_ENABLED_COMPONENTS,
   MONITOR_CONTROL_GET_PRETRIGGER_EVENTS_TO_SAVE,
   MONITOR_CONTROL_SET_PRETRIGGER_EVENTS_TO_SAVE,
   MONITOR_CONTROL_GET_MAX_EVENTS_IN_SESSION,
   MONITOR_CONTROL_SET_MAX_EVENTS_IN_SESSION,
} RTX64_MONITOR_CONTROL_OP;

Constants

MONITOR_CONTROL_RESERVED

Reserved. Do not use.

MONITOR_CONTROL_START

Start RTX64 monitoring. For information on monitoring states, see Using RTX64 Monitor.

MONITOR_CONTROL_PAUSE

Pause the collection of monitoring events during the current session without creating a new session folder. For information on monitoring states, see Using the Monitor Utility.

MONITOR_CONTROL_RESUME

Resume the monitoring session from a paused state. For information on monitoring states, see Using RTX64 Monitor.

MONITOR_CONTROL_STOP

Stop RTX64 monitoring. For information on monitoring states, see Using RTX64 Monitor.

MONITOR_CONTROL_ENABLE_EVENTS

Enable monitoring events.

The following monitoring events are not generated in RTX64 4.3 and later versions and will be silently ignored by operation MONITOR_CONTROL_ENABLE_EVENTS:

MONITOR_CONTROL_DISABLE_EVENTS

Disable monitoring events.

The following monitoring events are not generated in RTX64 4.3 and later versions and will be silently ignored by operation MONITOR_CONTROL_DISABLE_EVENTS:

MONITOR_CONTROL_SET_EVENT_TRIGGERS

This operation sets triggers for monitoring events.

Parameter data should point to an array of MF_TRIGGERS that contains exactly MF_EVENT_KIND_MAX elements, each of which specifies the triggers to set for the corresponding enumerator in enumeration MF_EVENT_KIND.

NOTE: Each bit that is set in this array represents a trigger to be set. Bits in this array that are zero do not set or reset any triggers.

When this function returns, the contents of the array pointed to by parameter data represents the triggers that are set for each event kind.

NOTE: This operation can only increase the number of triggers that are set. Use operation MONITOR_CONTROL_RESET_EVENT_TRIGGERS to reset (i.e., turn off) triggers for certain events.

The following kinds of monitoring events cannot be associated with triggers:

Attempting to do so will cause RtMonitorControl to fail with ERROR_INVALID_PARAMETER.

The following monitoring events are not generated in RTX64 4.3 and later versions and cannot be set as session start and/or stop triggers:

  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_ALLOC (Contiguous Memory Alloc)
  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_ALLOC_FAIL (Contiguous Memory Alloc Fail)
  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_SPECIFY_CACHE (Contiguous Memory Alloc Specify Cache)
  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_SPECIFY_CACHE_FAIL (Contiguous Memory Alloc Specify Cache Fail)
  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_FREE (Contiguous Memory Free)
  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_FAIL (Contiguous Memory Free Fail)
  • MF_EVENT_KIND_LOCAL_MEMORY_EXPAND (Local Memory Expand)
  • MF_EVENT_KIND_LOCAL_MEMORY_SHRINK (Local Memory Shrink)
  • MF_EVENT_KIND_WINDOWS_MEMORY_ALLOC (Windows Memory Alloc)
  • MF_EVENT_KIND_WINDOWS_MEMORY_ALLOC_FAIL (Windows Memory Alloc Fail)
  • MF_EVENT_KIND_WINDOWS_MEMORY_FREE (Windows Memory Free)
  • MF_EVENT_KIND_WINDOWS_MEMORY_FREE_FAIL (Windows Memory Free Fail)

These events will be ignored by operation MONITOR_CONTROL_SET_EVENT_TRIGGERS.

MONITOR_CONTROL_RESET_EVENT_TRIGGERS

This operation resets (i.e., turns off) triggers for monitoring events.

Parameter data should point to an array of MF_TRIGGERS that contains exactly MF_EVENT_KIND_MAX elements, each of which specifies the triggers to reset for the corresponding enumerator in enumeration MF_EVENT_KIND.

NOTE: Each bit that is set in this array represents a trigger to be reset. Bits in this array that are zero do not set or reset any triggers.

When this function returns, the contents of the array pointed to by parameter data represents the triggers that are set for each event kind.

NOTE: This operation can only decrease the number of triggers that are set. Use operation MONITOR_CONTROL_SET_EVENT_TRIGGERS to set triggers for certain events.

The following kinds of monitoring events cannot be associated with triggers:

Attempting to do so will cause RtMonitorControl to fail with ERROR_INVALID_PARAMETER.

The following monitoring events are not generated in RTX64 4.3 and later versions and cannot be set as session start and/or stop triggers:

  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_ALLOC (Contiguous Memory Alloc)
  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_ALLOC_FAIL (Contiguous Memory Alloc Fail)
  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_SPECIFY_CACHE (Contiguous Memory Alloc Specify Cache)
  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_SPECIFY_CACHE_FAIL (Contiguous Memory Alloc Specify Cache Fail)
  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_FREE (Contiguous Memory Free)
  • MF_EVENT_KIND_CONTIGUOUS_MEMORY_FAIL (Contiguous Memory Free Fail)
  • MF_EVENT_KIND_LOCAL_MEMORY_EXPAND (Local Memory Expand)
  • MF_EVENT_KIND_LOCAL_MEMORY_SHRINK (Local Memory Shrink)
  • MF_EVENT_KIND_WINDOWS_MEMORY_ALLOC (Windows Memory Alloc)
  • MF_EVENT_KIND_WINDOWS_MEMORY_ALLOC_FAIL (Windows Memory Alloc Fail)
  • MF_EVENT_KIND_WINDOWS_MEMORY_FREE (Windows Memory Free)
  • MF_EVENT_KIND_WINDOWS_MEMORY_FREE_FAIL (Windows Memory Free Fail)

These events will be ignored by operation MONITOR_CONTROL_RESET_EVENT_TRIGGERS.

MONITOR_CONTROL_SET_CUSTOM_EVENT_TRIGGERS

This operation that sets triggers for custom monitoring events.

Parameter data should point to an array of MF_TRIGGERS that contains exactly MF_TRIGGERS_FOR_CUSTOM_EVENT_IDS_MAX elements, each of which specifies the triggers to set for the corresponding custom event kind.

NOTE: Each bit that is set in this array represents a trigger to be set. Bits in this array that are zero do not set or reset any triggers. Parameter size is ignored for this operation.

When this function returns, the contents of the array pointed to by parameter data represents the triggers that are set for each custom event kind in the range 0 to MF_TRIGGERS_FOR_CUSTOM_EVENT_IDS_MAX - 1.

NOTE: This operation can only increase the number of triggers that are set. Use operation MONITOR_CONTROL_RESET_CUSTOM_EVENT_TRIGGERS to reset (i.e., turn off) triggers for certain custom event kinds.

MONITOR_CONTROL_RESET_CUSTOM_EVENT_TRIGGERS

This operation resets (i.e., turns off) triggers for custom monitoring events.

Parameter data should point to an array of MF_TRIGGERS that contains exactly MF_TRIGGERS_FOR_CUSTOM_EVENT_IDS_MAX elements, each of which specifies the triggers to reset for the corresponding custom event kind.

NOTE: Each bit that is set in this array represents a trigger to be reset. Bits in this array that are zero do not set or reset any triggers.

When this function returns, the contents of the array pointed to by parameter data represents the triggers that are set for each custom event kind in the range 0 to MF_TRIGGERS_FOR_CUSTOM_EVENT_IDS_MAX - 1.

NOTE: This operation can only decrease the number of triggers that are set. Use operation MONITOR_CONTROL_SET_CUSTOM_EVENT_TRIGGERS to set triggers for certain custom event kinds.

MONITOR_CONTROL_ENABLE_COMPONENTS

This operation toggles generation of monitoring events by one or more RTX64 product components. Changes made by this operation are transient, and last only until the RTX64 Subsystem stops. To persistently change which components have event generation enabled, use Managed Framework API Monitor.Subsystem.EnableComponents.

Parameter data points to a 64-bit unsigned integer that is the bitwise OR of enumerators from enumeration RT_MONITOR_COMPONENT, where each set bit represents a product component that will have its event generation toggled between enabled and disabled. Parameter size must be set to 8 (e.g., sizeof(unsigned __int64)).

If successful, this function returns TRUE, otherwise it returns FALSE and sets the last error value.

MONITOR_CONTROL_GET_ENABLED_COMPONENTS

This operation retrieves the transient configuration of RTX64 product components that currently have monitoring event generation enabled. Parameter data points to a 64-bit unsigned integer that is set to the bitwise OR of enumerators from enumeration RT_MONITOR_COMPONENT, where each set bit represents a product component that has event generation enabled. Parameter size must bet set to 8 (e.g., sizeof(unsigned __int64)).

MONITOR_CONTROL_GET_PRETRIGGER_EVENTS_TO_SAVE

Retrieves the transient value of the number of pre-start-trigger events to save in a monitor session. Pre-start-trigger events are events that occur before the event that triggers the start of a monitoring session.

Parameter data points to an unsigned 32-bit integer holding the retrieved transient value.

Parameter size must be set to 4 (e.g. sizeof(unsigned __int32)).

If successful, this function returns TRUE, otherwise it returns FALSE and sets the last error value.

MONITOR_CONTROL_SET_PRETRIGGER_EVENTS_TO_SAVE

Sets the transient value of the number of pre-start-trigger events to save in a monitor session. Pre-start-trigger events are events that occur before the event that triggers the start of a monitoring session.

The number of pre-start-trigger events to save must not exceed the maximum number of events to save in a given session.

Parameter data points to an unsigned 32-bit integer holding the value to be set transiently.

Parameter size must be set to 4 (e.g. sizeof(unsigned __int32)).

If successful, this function returns TRUE, otherwise it returns FALSE and sets the last error value.

MONITOR_CONTROL_GET_MAX_EVENTS_IN_SESSION

Retrieves the transient value of the maximum number of events to save in a monitor session.

Parameter data points to an unsigned 32-bit integer holding the retrieved transient value.

Parameter size must be set to 4 (e.g. sizeof(unsigned __int32)).

If successful, this function returns TRUE, otherwise it returns FALSE and sets the last error value.

MONITOR_CONTROL_SET_MAX_EVENTS_IN_SESSION

Sets the transient value of the maximum number of events to save in a monitor session.

This value must not be 0, and may be set to the maximum size of an unsigned __int32 (e.g. UINT32_MAX or 0xFFFFFFFF) to represent unlimited events. The Maximum number of events to save must not be less than the number of Pre-trigger events.

Parameter data points to an unsigned 32-bit integer holding the value to be set transiently.

Parameter size must be set to 4 (e.g. sizeof(unsigned __int32)).

NOTE: If a monitoring session is already in progress, reducing this value may cause monitoring to stop, if the monitoring stop behavior is set to Automatic, or lose saved data is stop behavior is set to Manual.

If successful, this function returns TRUE, otherwise it returns FALSE and sets the last error value.

Remarks

A trigger causes one of a set of pre-defined effects when monitoring is enabled and a given event can be generated, even if that event is disabled. For instance, if the trigger MF_TRIGGER_START_MONITORING is set for event MF_EVENT_KIND_THREAD_SLEEP, then when that event can be generated (even if that event is disabled), the trigger will cause monitoring to start.

The operations MONITOR_CONTROL_SET_EVENT_TRIGGERS, MONITOR_CONTROL_RESET_EVENT_TRIGGERS, MONITOR_CONTROL_SET_CUSTOM_EVENT_TRIGGERS, and MONITOR_CONTROL_RESET_CUSTOM_EVENT_TRIGGERS can be performed at any time, and their effects remain until the RTX64 Subsystem stops, but triggers do nothing unless monitoring is enabled. Monitoring does not need to be started for triggers to work.

This function is only deterministic from the RTSS side.

Requirements

Minimum Supported Version

These constants were added in RTX64 4.2:

  • MONITOR_CONTROL_GET_PRETRIGGER_EVENTS_TO_SAVE
  • MONITOR_CONTROL_SET_PRETRIGGER_EVENTS_TO_SAVE
  • MONITOR_CONTROL_GET_MAX_EVENTS_IN_SESSION
  • MONITOR_CONTROL_SET_MAX_EVENTS_IN_SESSION

These constants were added in RTX64 3.6:

  • MONITOR_CONTROL_PAUSE
  • MONITOR_CONTROL_RESUME
  • MONITOR_CONTROL_ENABLE_COMPONENTS
  • MONITOR_CONTROL_GET_ENABLED_COMPONENTS

RTX64 3.4 (availability from RTSS and Windows applications)

RTX64 2014 (availability from RTSS applications only)
Header

Rtapi.h
Library rtx_rtss.lib (RTSS), rtapi.h (Windows)

See Also:

RtMonitorControl

RtMonitorChangeState

MF_EVENT_KIND