Notification proposal

Common.tex

@@ -23,6 +23,7 @@
 \item{\textbf{Attribute} functions expose measurement and control functionality, }
 \item{\textbf{Metadata} functions allow the user to access additional information about objects and attributes (often device or instrumentation specific information), }
 \item{\textbf{Statistics} functions are used to generate statistical information based on fundamental attribute information (measurements),}
+\item{\textbf{Agents} functions that are used to register agent code for a given object to receive notifications sent to that object,}
 \end{itemize}
 and other functionality that is common across a number of interfaces.
 
@@ -808,6 +809,22 @@ \section{Statistics Functions}\label{sec:StatisticsFunctions}
 %=============================================================================%
 %=============================================================================%
 %=============================================================================%
+\section{Agent Functions}\label{sec:AgentFunctions}
+%
+
+The agents functions provide an interface to attach function pointers to notification handling code for a given object. 
+This is useful for passing messages between different levels of the Power API interfaces.
+For example, a job level power/energy manager can attach to an object in the system which can then recieve notifications from other layers of the Power API interfaces. 
+In this example a job manager can receive notifications from a resource manager that indicate changing power caps for a given job. 
+From the job manager's perspective, it can use notifications to request changes in power cap from the resource manager using the same notification interface. 
+
+Agent functions must register to a specific Power API object, and must include a function pointer to code meant to handle incoming notifications.
+Notifications include a versioning number in the \texttt{PWR_Note} type that can help the notification handler code to interpret the notification details included in the \texttt{PWR_Note} struct. 
+%
+
+
+
+
 %=============================================================================%
 %=============================================================================%
 %=============================================================================%

RMOS.tex

@@ -56,3 +56,16 @@ \subsection{Supported High-Level (Common) Functions}\label{sec:RMOSHighLevel}
 %==============================================================================%
 
 \subsection{Interface Specific Functions}\label{sec:RMOSFunctions}
+
+%=============================================================================%
+%int    PWR_ObjGetName( PWR_Obj object, char* dest, size_t len );
+\begin{prototype}{NotifyToNode}
+	\longdescription{The \texttt{PWR_NotifyToNode} function provides data in a notification object to the OS/node level from the system (resource manager/scheduler) level. This function is useful for reporting non-standard operating conditions directly to the node, bypassing intermediate layers For example, in the case where a job is being managed by an intelligent job manager, this function can notify the node that something has gone wrong with the job in the event that the job manager is incapable of providing this information. This is important as the operating conditions that were provided at a job-level may be violated if an error occurs. Therefore this solution allows the system to notify nodes of what to do. This is useufl if there are node level power/energy optimization runtimes in operation.}
+	\returntype{int}
+	\parameter{PWR_Note note}	{\pInput}	{The notification that the system wishes to transmit to the OS/node layer.}
+	\parameter{int agentid}    	{\pInput}	{The system agent target for the notification.}
+	\parameter{size_t len}    	{\pInput}	{The length of the user provided notification.}
+	\returnval{PWR_RET_FAILURE} 	{Upon FAILURE.}
+\end{prototype}
+
+

TypeDefs.tex

@@ -609,4 +609,59 @@ \subsubsection{PWR_PerfState}\label{type:PerfState}
 \end{minipage}
 \end{center}
 
+%==============================================================================%
+
+\subsubsection{PWR_NoteType}\label{type:NoteType}
+
+The \texttt{PWR_NoteType} type is generalized notification classification mechanism,
+allowing notifications to carry a basic type for handling at the target.
+
+\begin{center}
+\begin{minipage}{.95\linewidth}%
+\begin{lstlisting}
+typedef enum {
+        PWR_NOTE_FATAL_FAILURE = 0,
+        PWR_NOTE_JOB_FAILURE,
+        PWR_NOTE_RESTART,
+        PWR_NOTE_CAP_VIOLATION,
+        PWR_NOTE_NODE_FAILURE,
+        PWR_NOTE_NODE_UNRESPONSIVE,
+        PWR_NOTE_RESUME_NORMAL,
+        /* */
+        PWR_NOTE_INVALID       = -1,
+        PWR_NOTE_NOT_SPECIFIED = -2
+} PWR_NoteType; 
+\end{lstlisting}
+\end{minipage}
+\end{center}
+
+
+%==============================================================================%
+
+\subsubsection{PWR_Note}\label{type:Note}
+
+The \texttt{PWR_Note} type is a structure that encapsulates an entire desirable 
+notification between higher lever system layers and lower level interfaces. For example,
+such notifications can be passed between a resource manager and an indiviudal node, bypassing
+intermediate layers like a job manager and vice versa. \texttt{PWR_NoteType} must be a valid
+type as defined in section~\ref{type:NoteType}. The \texttt{note_details} field can contain a 
+string with additional information on the notification following the required notation from
+the sending/receving software. \texttt{source_id} should contain the source node's numbering,
+perferrably the Power API object ID.  
+
+\begin{center}
+\begin{minipage}{.95\linewidth}%
+\begin{lstlisting}
+typedef struct {
+        PWR_NoteType note;
+        uint64_t version;
+        char * note_details;
+        uint64_t note_len;
+        char * source_id;
+        uint64_t source_id_len;
+} PWR_Note;
+\end{lstlisting}
+\end{minipage}
+\end{center}
+
 

UserRM.tex

@@ -43,3 +43,15 @@ \subsection{Supported High-Level (Common) Functions}\label{sec:UserRMHighLevel}
 
 \subsection{Interface Specific Functions}\label{sec:UserRMFunctions}
 
+%=============================================================================%
+%int    PWR_ObjGetName( PWR_Obj object, char* dest, size_t len );
+\begin{prototype}{NotifyToSystem}
+	\longdescription{The \texttt{PWR_NotifyToSystem} function provides data in a notification object to the system from the user level. This function is useful for reporting non-standard operating conditions to the higher level resource manager. For example, in the case where a job is being managed by an intelligent job manager, this function can report to the resource manager/scheduler that something has gone wrong with the job in the event that the job manager is incapable of providing this information.}
+	\returntype{int}
+	\parameter{PWR_Note note}	{\pInput}	{The notification that the  user wishes to transmit to the resource manager.}
+	\parameter{PWR_Obj agent_obj}    	{\pInput}	{The system object that is the target of the notification.}
+	\parameter{size_t len}    	{\pInput}	{The length of the user provided notification.}
+	\returnval{PWR_RET_FAILURE} 	{Upon FAILURE.}
+\end{prototype}
+
+