Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

monitor.h File Reference

Detailed Description

Aware Monitor

Introduction

The Monitor is the heart of the Aware system. Its job is to managar a set of "handlers". Handlers may arrange to recieve alarms, software interrupts or fd notifcations. Handlers may generate events themselves allowing a forward chaining of event/handler actions.

As a simple example of using the monitor, consider an application that generates email alarms based on the free memory of a system. This is implemented as:

  1. a "handler" that reads the free memory in the system every 1sec and generates an event containing the amount of free memory.

  2. a handler that receives the event and compares to a user defined threshold and sends an email if the free memory drops below the threshold

The Monitor provides an extensible framework for adding handlers. The hope is that a rich set of probes and condition handlers can be created such that systems can control themselves by adapting to changing conditions.

Bits and Pieces

There are 4 main components to the Monitor:

  1. Alarm Queue (thread)

  2. Event Relay Queue

  3. FD Relay Queue (signal handler for Handler Queue)

  4. Handler Queue (thread)

Events are generated by the Alarm Queue thread and the FD Relay Queue thread and are sent to the Event Relay Queue which acts as a synchronization point. When the Handler thread is ready to process more events it takes them from the Event Relay Queue. Event resource management is the responsibilty of the Event Relay Queue. The Alarm Queue gets new Events from the Event Relay Queue, while the Handler Queue returns processed Events to the Event Relay Queue for reuse by the Alarm Queue and FD Relay Queue, respectively.

Handlers are expected to execute as quickly possible. If processing interferes with the duty cycle it is suggested the developer run them as a "tasklet". Tasklets execute in a seperate thread and are useful for long running codes as well as codes that use blocking system calls. It is up to the implementor to handle synchronization and state.

The duty cycle for the Alarm Queue is:
Define: probe_cycle_time = AW_DEFAULT_ALARM_CYCLE_TIME (can be changed)

  1. get current time

  2. execute each alarm scheduled to run in this time slice, collect events into list

  3. aquire lock on Event Relay

  4. add collected events to the Event Relay Queue

  5. release lock on Event Relay Queue

  6. get current time

  7. calculate probe_cycle_time - (#6 - #1 )

  8. if #7 > 0 then nanosleep(#7)

  9. goto #1

The duty cycle for the Handler Queue is:

  1. aquire lock on Event Relay / wait for wakeup

  2. get current time

  3. return used events to Event Relay Queue and FD Relay Queue

  4. collect events from alarms + fd events + any SELF generated events , then dispatch to q's associated with each handler

    Handlers can register to match events:

  5. release lock on Event Relay Queue

  6. execute each event handler against its assocated event q

  7. goto #1

#include "sysnet.h"
#include "util.h"
#include "address.h"
#include "hash.h"
#include "mask.h"
#include "log.h"
#include "monsignals.h"
#include "monthread.h"
#include "event.h"
#include "alarm.h"
#include "handler.h"
#include "tasklet.h"

Go to the source code of this file.

Data Structures

struct  aw_handler_q_s
struct  aw_monitor_alarm_q_t
struct  aw_monitor_fd_q_info_t
struct  aw_monitor_fd_q_t
struct  aw_monitor_fd_relay_t
struct  aw_monitor_handler_fdcallback_s
struct  aw_monitor_handler_irecallback_s
struct  aw_monitor_handler_q_t
struct  aw_monitor_params_t
struct  aw_monitor_relay_t
struct  aw_monitor_s
struct  aw_monitor_sched_s
struct  aw_monitor_xaction_state_s

Defines

#define AW_ALARM_THREAD_STACKSIZE   (8*1024)
#define AW_DEFAULT_ALARM_CACHE_SIZE   256
#define AW_DEFAULT_EVENT_CACHE_SIZE   256
#define AW_DEFAULT_FDCALLBACK_CACHE_SIZE   256
#define AW_DEFAULT_IRECALLBACK_CACHE_SIZE   256
#define AW_FD_QSIZE   1024
#define AW_HANDLER_THREAD_STACKSIZE   (128*1024)
#define AW_MONITOR_DEFAULT_PARAMS
#define AW_MONITOR_LOGGER_DEFAULT_MINLEVEL   AW_INFO_LOG_LEVEL
#define AW_MONITOR_LOGGER_DEFAULT_PARAMS
#define AW_MONITOR_SCHED_DEFAULT_PARAMS
#define AW_TASKLET_THREAD_STACKSIZE   (512*1024)

Typedefs

typedef aw_mask_t aw_handler_maskqlookup_t
typedef aw_handler_q_s aw_handler_q_t
typedef aw_hash32_t aw_handler_qlookup_t
typedef aw_monitor_handler_fdcallback_s aw_monitor_handler_fdcallback_t
typedef aw_monitor_handler_irecallback_s aw_monitor_handler_irecallback_t
typedef aw_monitor_sched_s aw_monitor_sched_t
typedef aw_monitor_s aw_monitor_t
typedef aw_monitor_xaction_state_s aw_monitor_xaction_state_t

Enumerations

enum  aw_monitor_state_t {
  AW_MONITOR_STOP_STATE, AW_MONITOR_RUN_STATE, AW_MONITOR_PAUSE_STATE, AW_MONITOR_FUBAR_STATE,
  AW_MONITOR_NSTATES
}

Functions

aw_handlerid_t aw_add_handler (aw_monitor_t *mon, aw_handler_t *handler)
 Add handler to list of executing handlers.

int32_t aw_add_handler_fdcallback (aw_monitor_t *mon, aw_handler_t *handler, int32_t fd, aw_handler_code_t(*fdcallback)(aw_handler_args_t *args, int32_t fd))
 Register a callback to be called when data is available on fd for a handler. Only executed for RUNNING handler. Relationship is 1-1 for fd to handler.

int32_t aw_add_handler_irecallback (aw_monitor_t *mon, aw_handler_t *handler, aw_address_t ire_id, aw_alarm_sched_t *sched, aw_handler_code_t(*callback)(aw_handler_args_t *args, aw_event_t *e))
 Register a callback to be called for every "interrupt" event.Only executed for RUNNING handler. Relationship is 1-1 for fd to handler.

aw_monitor_t * aw_create_monitor (aw_monitor_params_t *params)
 Malloc , clear, set, init mutex, return object.

void aw_destroy_monitor (aw_monitor_t *mon)
 Cleanup , free resources.

void aw_monitor_append_event (aw_event_t *event, aw_monitor_t *mon)
 Send event to handlers.

void aw_monitor_append_q (aw_event_q_t *q, aw_monitor_t *mon)
 Dump contents of q to handlers.

void aw_monitor_float32_event (aw_monitor_t *mon, aw_event_sig_t *event_sig, float32_t val)
 Send float32 event to handlers.

void aw_monitor_float64_event (aw_monitor_t *mon, aw_event_sig_t *event_sig, float64_t val)
 Send float64 event to handlers.

void aw_monitor_int32_event (aw_monitor_t *mon, aw_event_sig_t *event_sig, u_int32_t val)
 Send int32 event to handlers.

void aw_monitor_int64_event (aw_monitor_t *mon, aw_event_sig_t *event_sig, u_int64_t val)
 Send int64 event to handlers.

void aw_monitor_logstats (aw_monitor_t *mon, aw_logger_t *logger)
 Print monitor stats to logger.

void aw_monitor_string_event (aw_monitor_t *mon, aw_event_sig_t *event_sig, byte_t *val, int32_t dup)
 Send string event to handlers, NOTE: this will free the string later!

void aw_monitor_timestamp_event (aw_monitor_t *mon, aw_event_sig_t *event_sig, aw_timestamp_t val)
 Send timestamp event to handlers.

aw_address_t aw_next_event_id (aw_monitor_t *mon)
 Increment and return event id.

void aw_remove_handler (aw_monitor_t *mon, aw_handlerid_t id)
 Remove handler from list of executing handlers.

int32_t aw_remove_handler_fdcallback (aw_monitor_t *mon, int32_t fd)
 Unregister a callback to be called when data is available on fd.

int32_t aw_remove_handler_irecallback (aw_monitor_t *mon, aw_address_t ire_id)
 Unregister a callback.

void aw_reschedule_handler (aw_monitor_t *mon, aw_handler_t *handler, aw_alarm_sched_t *sched)
 Alter an existing schedule for a handler.

aw_address_t aw_reserve_event_mask_bit (aw_monitor_t *mon)
 Returns a mask with 1 bit set guaranteed to be unique.

void aw_signal_handler_irecallback (aw_monitor_t *mon, aw_address_t ire_id)
 Sends an interrupt event to cause the handler to run.

int32_t aw_wait_monitor (aw_monitor_t *mon)
 Block until all monitor threads exit.

Define Documentation

#define AW_ALARM_THREAD_STACKSIZE   (8*1024)
 

#define AW_DEFAULT_ALARM_CACHE_SIZE   256
 

#define AW_DEFAULT_EVENT_CACHE_SIZE   256
 

#define AW_DEFAULT_FDCALLBACK_CACHE_SIZE   256
 

#define AW_DEFAULT_IRECALLBACK_CACHE_SIZE   256
 

#define AW_FD_QSIZE   1024
 

#define AW_HANDLER_THREAD_STACKSIZE   (128*1024)
 

#define AW_MONITOR_DEFAULT_PARAMS
 

Value:

{ \
 .logger_params = AW_MONITOR_LOGGER_DEFAULT_PARAMS , \
 .sched = AW_MONITOR_SCHED_DEFAULT_PARAMS \
}
Default parameters for monitor constructor

#define AW_MONITOR_LOGGER_DEFAULT_MINLEVEL   AW_INFO_LOG_LEVEL
 

#define AW_MONITOR_LOGGER_DEFAULT_PARAMS
 

Value:

{ \
\
 .filename = NULL,\
\
 /* stderr */ \
 .fd = 2, \
 \
 .min_level = AW_MONITOR_LOGGER_DEFAULT_MINLEVEL,\
\
 .max_level = AW_ERROR_LOG_LEVEL, \
\
 .strlevel = NULL, \
\
 .flags = AW_LOGGER_DEFAULT_FLAGS, \
\
 .error_logger = NULL \
}
Default parameters for default monitor logger init

#define AW_MONITOR_SCHED_DEFAULT_PARAMS
 

Value:

{\
\
 .policy = SCHED_OTHER, \
 .params.sched_priority = 0 \
}

#define AW_TASKLET_THREAD_STACKSIZE   (512*1024)
 

Typedef Documentation

typedef aw_mask_t aw_handler_maskqlookup_t
 

typedef struct aw_handler_q_s aw_handler_q_t
 

typedef aw_hash32_t aw_handler_qlookup_t
 

typedef struct aw_monitor_handler_fdcallback_s aw_monitor_handler_fdcallback_t
 

typedef struct aw_monitor_handler_irecallback_s aw_monitor_handler_irecallback_t
 

typedef struct aw_monitor_sched_s aw_monitor_sched_t
 

typedef struct aw_monitor_s aw_monitor_t
 

typedef struct aw_monitor_xaction_state_s aw_monitor_xaction_state_t
 

Enumeration Type Documentation

enum aw_monitor_state_t
 

State codes for monitor

Enumeration values:
AW_MONITOR_STOP_STATE 
AW_MONITOR_RUN_STATE 
AW_MONITOR_PAUSE_STATE 
AW_MONITOR_FUBAR_STATE 
AW_MONITOR_NSTATES 

Function Documentation

aw_handlerid_t aw_add_handler (  aw_monitor_t *  mon,
aw_handler_t *  handler
) 
 

Add handler to list of executing handlers.

aw_add_handler

Parameters:
mon Monitor ptr
handler Handler ptr
Returns:
Returns generated id of handler (needed in aw_remove_handler)

int32_t aw_add_handler_fdcallback (  aw_monitor_t *  mon,
aw_handler_t *  handler,
int32_t  fd,
aw_handler_code_t(*  fdcallback)(aw_handler_args_t *args, int32_t fd)
) 
 

Register a callback to be called when data is available on fd for a handler. Only executed for RUNNING handler. Relationship is 1-1 for fd to handler.

aw_add_handler_fdcallback

Parameters:
mon Monitor ptr
handler Handler ptr
fd File desciptor
fdcallback Callback
Returns:
Returns non-zero if error

int32_t aw_add_handler_irecallback (  aw_monitor_t *  mon,
aw_handler_t *  handler,
aw_address_t  ire_id,
aw_alarm_sched_t *  sched,
aw_handler_code_t(*  callback)(aw_handler_args_t *args, aw_event_t *e)
) 
 

Register a callback to be called for every "interrupt" event.Only executed for RUNNING handler. Relationship is 1-1 for fd to handler.

aw_add_handler_irecallback

Parameters:
mon Monitor ptr
handler Handler ptr
ire_id Event address for alarm
sched Pointer to schedule for alarm
callback Callback function
Returns:
Returns non-zero if error

aw_monitor_t* aw_create_monitor (  aw_monitor_params_t *  params  ) 
 

Malloc , clear, set, init mutex, return object.

aw_create_monitor

Parameters:
params Options struct ptr, NULL is okay (implies defaults)
Returns:
Monitor ptr

void aw_destroy_monitor (  aw_monitor_t *  mon  ) 
 

Cleanup , free resources.

aw_destroy_monitor

Parameters:
mon Monitor ptr

void aw_monitor_append_event (  aw_event_t *  event,
aw_monitor_t *  mon
) 
 

Send event to handlers.

aw_monitor_append_event

Parameters:
event Event ptr
mon Monitor ptr

void aw_monitor_append_q (  aw_event_q_t *  q,
aw_monitor_t *  mon
) 
 

Dump contents of q to handlers.

aw_monitor_append_q

Parameters:
q Event Q ptr
mon Monitor ptr

void aw_monitor_float32_event (  aw_monitor_t *  mon,
aw_event_sig_t *  event_sig,
float32_t  val
) 
 

Send float32 event to handlers.

aw_monitor_float32_event

Parameters:
mon Monitor
event_sig Event signature
val Value

void aw_monitor_float64_event (  aw_monitor_t *  mon,
aw_event_sig_t *  event_sig,
float64_t  val
) 
 

Send float64 event to handlers.

aw_monitor_float64_event

Parameters:
mon Monitor
event_sig Event signature
val Value

void aw_monitor_int32_event (  aw_monitor_t *  mon,
aw_event_sig_t *  event_sig,
u_int32_t  val
) 
 

Send int32 event to handlers.

aw_monitor_int32_event

Parameters:
mon Monitor
event_sig Event signature
val Value

void aw_monitor_int64_event (  aw_monitor_t *  mon,
aw_event_sig_t *  event_sig,
u_int64_t  val
) 
 

Send int64 event to handlers.

aw_monitor_int64_event

Parameters:
mon Monitor
event_sig Event signature
val Value

void aw_monitor_logstats (  aw_monitor_t *  mon,
aw_logger_t *  logger
) 
 

Print monitor stats to logger.

aw_monitor_logstats

Parameters:
mon Monitor
logger Logger

void aw_monitor_string_event (  aw_monitor_t *  mon,
aw_event_sig_t *  event_sig,
byte_t *  val,
int32_t  dup
) 
 

Send string event to handlers, NOTE: this will free the string later!

aw_monitor_string_event

Parameters:
mon Monitor
event_sig Event signature
val String value
dup If non-zero strdup() string inside function. Usually you want this.

void aw_monitor_timestamp_event (  aw_monitor_t *  mon,
aw_event_sig_t *  event_sig,
aw_timestamp_t  val
) 
 

Send timestamp event to handlers.

aw_monitor_timestamp_event

Parameters:
mon Monitor
event_sig Event signature
val Value

aw_address_t aw_next_event_id (  aw_monitor_t *  mon  ) 
 

Increment and return event id.

aw_next_event_id

Parameters:
mon Monitor ptr
Returns:
Returns available event id

void aw_remove_handler (  aw_monitor_t *  mon,
aw_handlerid_t  id
) 
 

Remove handler from list of executing handlers.

aw_remove_handler

Parameters:
mon Monitor ptr
id Id returned from aw_add_handler()

int32_t aw_remove_handler_fdcallback (  aw_monitor_t *  mon,
int32_t  fd
) 
 

Unregister a callback to be called when data is available on fd.

aw_remove_handler_fdcallback

Parameters:
mon Monitor ptr
fd File desciptor
Returns:
Returns non-zero if error

int32_t aw_remove_handler_irecallback (  aw_monitor_t *  mon,
aw_address_t  ire_id
) 
 

Unregister a callback.

aw_remove_handler_irecallback

Parameters:
mon Monitor ptr
ire_id Event address for alarm
Returns:
Returns non-zero if error

void aw_reschedule_handler (  aw_monitor_t *  mon,
aw_handler_t *  handler,
aw_alarm_sched_t *  sched
) 
 

Alter an existing schedule for a handler.

aw_reschedule_handler

Parameters:
mon Monitor ptr
handler Handler ptr
sched The new run schedule

aw_address_t aw_reserve_event_mask_bit (  aw_monitor_t *  mon  ) 
 

Returns a mask with 1 bit set guaranteed to be unique.

aw_reserve_event_mask_bit

Parameters:
mon Monitor ptr
Returns:
Mask w/1 bit set or 0 when all available bits used

void aw_signal_handler_irecallback (  aw_monitor_t *  mon,
aw_address_t  ire_id
) 
 

Sends an interrupt event to cause the handler to run.

aw_signal_handler_irecallback

Parameters:
mon Monitor ptr
ire_id Event address for alarm

int32_t aw_wait_monitor (  aw_monitor_t *  mon  ) 
 

Block until all monitor threads exit.

aw_wait_monitor

Parameters:
mon Monitor ptr
Returns:
Return 0 on success

Aware 0.11.1 Copyright (C) 1998-2005 Russell Leighton (russ@elegant-software.com)