\doxysection{Finite State Machine abstraction}
\label{group__fsm}\index{Finite State Machine abstraction@{Finite State Machine abstraction}}


Finite State Machine abstraction.  


\doxysubsection*{Files}
\begin{DoxyCompactItemize}
\item 
file \textbf{ fsm.\+h}
\begin{DoxyCompactList}\small\item\em Finite State Machine. \end{DoxyCompactList}\item 
file \textbf{ fsm.\+c}
\begin{DoxyCompactList}\small\item\em Osmocom generic Finite State Machine implementation. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Data Structures}
\begin{DoxyCompactItemize}
\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+state}
\begin{DoxyCompactList}\small\item\em description of a rule in the FSM \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+fsm}
\begin{DoxyCompactList}\small\item\em a description of an osmocom finite state machine \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+inst}
\begin{DoxyCompactList}\small\item\em a single instanceof an osmocom finite state machine \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\#define \textbf{ LOGPFSMSL}(fi,  \textbf{ subsys},  \textbf{ level},  fmt,  args...)~  \textbf{ LOGPFSMSLSRC}(fi, \textbf{ subsys}, \textbf{ level}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+, fmt, \#\# args)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context, on explicit logging subsystem and level. \end{DoxyCompactList}\item 
\#define \textbf{ LOGPFSMSLSRC}(fi,  \textbf{ subsys},  \textbf{ level},  caller\+\_\+file,  caller\+\_\+line,  fmt,  args...)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context, on explicit logging subsystem and level, and passing explicit source file and line information. \end{DoxyCompactList}\item 
\#define \textbf{ LOGPFSML}(fi,  \textbf{ level},  fmt,  args...)~  \textbf{ LOGPFSMLSRC}(fi, \textbf{ level}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+, fmt, \#\# args)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context, on explicit logging level. \end{DoxyCompactList}\item 
\#define \textbf{ LOGPFSMLSRC}(fi,  \textbf{ level},  caller\+\_\+file,  caller\+\_\+line,  fmt,  args...)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context, on explicit logging level, and with explicit source file and line info. \end{DoxyCompactList}\item 
\#define \textbf{ LOGPFSM}(fi,  fmt,  args...)~  \textbf{ LOGPFSML}(fi, (fi) ? (fi)-\/$>$log\+\_\+level \+: \textbf{ LOGL\+\_\+\+ERROR}, fmt, \#\# args)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context. \end{DoxyCompactList}\item 
\#define \textbf{ LOGPFSMSRC}(fi,  caller\+\_\+file,  caller\+\_\+line,  fmt,  args...)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context, with explicit source file and line info. \end{DoxyCompactList}\item 
\#define \textbf{ OSMO\+\_\+\+T\+\_\+\+FMT}~\char`\"{}\%c\%\textbf{ u}\char`\"{}
\item 
\#define \textbf{ OSMO\+\_\+\+T\+\_\+\+FMT\+\_\+\+ARGS}(T)~((T) $>$= 0 ? \textquotesingle{}T\textquotesingle{} \+: \textquotesingle{}X\textquotesingle{}), ((T) $>$= 0 ? (T) \+: -\/(T))
\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg}(fi,  new\+\_\+state,  timeout\+\_\+secs,  T)
\begin{DoxyCompactList}\small\item\em perform a state change of the given FSM instance \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+ms}(fi,  new\+\_\+state,  timeout\+\_\+ms,  T)
\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer}(fi,  new\+\_\+state)
\begin{DoxyCompactList}\small\item\em perform a state change while keeping the current timer running. \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer}(fi,  new\+\_\+state,  timeout\+\_\+secs,  T)
\begin{DoxyCompactList}\small\item\em perform a state change while keeping the current timer if running, or starting a timer otherwise. \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer\+\_\+ms}(fi,  new\+\_\+state,  timeout\+\_\+ms,  T)
\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch}(fi,  \textbf{ event},  \textbf{ data})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch}(fi, \textbf{ event}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)
\begin{DoxyCompactList}\small\item\em dispatch an event to an osmocom finite state machine instance \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+term}(fi,  \textbf{ cause},  \textbf{ data})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term}(fi, \textbf{ cause}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)
\begin{DoxyCompactList}\small\item\em Terminate FSM instance with given cause. \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children}(fi,  \textbf{ cause},  \textbf{ data})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children}(fi, \textbf{ cause}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)
\begin{DoxyCompactList}\small\item\em Terminate all child FSM instances of an FSM instance. \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children}(fi,  \textbf{ cause},  \textbf{ data})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children}(fi, \textbf{ cause}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)
\begin{DoxyCompactList}\small\item\em dispatch an event to all children of an osmocom finite state machine instance \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Enumerations}
\begin{DoxyCompactItemize}
\item 
enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause} \{ \newline
\textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+PARENT}
, \newline
\textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+REQUEST}
, \newline
\textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+REGULAR}
, \newline
\textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+ERROR}
, \newline
\textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+TIMEOUT}
 \}
\end{DoxyCompactItemize}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
static const char $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+name} (enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause} \textbf{ cause})
\item 
void \textbf{ osmo\+\_\+fsm\+\_\+log\+\_\+addr} (bool log\+\_\+addr)
\begin{DoxyCompactList}\small\item\em specify if FSM instance addresses should be logged or not \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+log\+\_\+timeouts} (bool log\+\_\+timeouts)
\begin{DoxyCompactList}\small\item\em Enable or disable logging of timeout values for FSM instance state changes. \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+safely} (bool term\+\_\+safely)
\begin{DoxyCompactList}\small\item\em Enable safer way to deallocate cascades of terminating FSM instances. \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx} (void $\ast$ctx)
\begin{DoxyCompactList}\small\item\em Instead of deallocating FSM instances, move them to the given talloc context. \end{DoxyCompactList}\item 
int \textbf{ osmo\+\_\+fsm\+\_\+register} (struct \textbf{ osmo\+\_\+fsm} $\ast$fsm)
\begin{DoxyCompactList}\small\item\em register a FSM with the core \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+unregister} (struct \textbf{ osmo\+\_\+fsm} $\ast$fsm)
\begin{DoxyCompactList}\small\item\em unregister a FSM from the core \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+fsm} $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+find\+\_\+by\+\_\+name} (const char $\ast$\textbf{ name})
\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+find\+\_\+by\+\_\+name} (const struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, const char $\ast$\textbf{ name})
\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+find\+\_\+by\+\_\+id} (const struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, const char $\ast$id)
\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc} (struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, void $\ast$ctx, void $\ast$priv, int log\+\_\+level, const char $\ast$id)
\begin{DoxyCompactList}\small\item\em allocate a new instance of a specified FSM \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc\+\_\+child} (struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$parent, uint32\+\_\+t parent\+\_\+term\+\_\+event)
\begin{DoxyCompactList}\small\item\em allocate a new instance of a specified FSM as child of other FSM instance \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+unlink\+\_\+parent} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, void $\ast$ctx)
\begin{DoxyCompactList}\small\item\em unlink child FSM from its parent FSM. \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+change\+\_\+parent} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$new\+\_\+parent, uint32\+\_\+t new\+\_\+parent\+\_\+term\+\_\+event)
\begin{DoxyCompactList}\small\item\em change parent instance of an FSM. \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+free} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi)
\begin{DoxyCompactList}\small\item\em delete a given instance of a FSM \end{DoxyCompactList}\item 
int \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, const char $\ast$id)
\begin{DoxyCompactList}\small\item\em Change id of the FSM instance. \end{DoxyCompactList}\item 
int \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id\+\_\+f} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, const char $\ast$fmt,...)
\begin{DoxyCompactList}\small\item\em Change id of the FSM instance using a string format. \end{DoxyCompactList}\item 
int \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id\+\_\+f\+\_\+sanitize} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, char replace\+\_\+with, const char $\ast$fmt,...)
\begin{DoxyCompactList}\small\item\em Change id of the FSM instance using a string format, and ensuring a valid id. \end{DoxyCompactList}\item 
const char $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+event\+\_\+name} (const struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, uint32\+\_\+t \textbf{ event})
\begin{DoxyCompactList}\small\item\em get human-\/readable name of FSM event \end{DoxyCompactList}\item 
const char $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+name} (const struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi)
\begin{DoxyCompactList}\small\item\em get human-\/readable name of FSM instance \end{DoxyCompactList}\item 
const char $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+state\+\_\+name} (const struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, uint32\+\_\+t state)
\begin{DoxyCompactList}\small\item\em get human-\/readable name of FSM state \end{DoxyCompactList}\item 
static const char $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+name} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi)
\begin{DoxyCompactList}\small\item\em return the name of the state the FSM instance is currently in. \end{DoxyCompactList}\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, unsigned long timeout\+\_\+secs, int T, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em perform a state change of the given FSM instance \end{DoxyCompactList}\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+ms} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, unsigned long timeout\+\_\+ms, int T, const char $\ast$\textbf{ file}, int line)
\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em perform a state change while keeping the current timer running. \end{DoxyCompactList}\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, unsigned long timeout\+\_\+secs, int T, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em perform a state change while keeping the current timer if running, or starting a timer otherwise. \end{DoxyCompactList}\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer\+\_\+ms} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, unsigned long timeout\+\_\+ms, int T, const char $\ast$\textbf{ file}, int line)
\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t \textbf{ event}, void $\ast$\textbf{ data}, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em dispatch an event to an osmocom finite state machine instance \end{DoxyCompactList}\item 
void \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause} \textbf{ cause}, void $\ast$\textbf{ data}, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em Terminate FSM instance with given cause. \end{DoxyCompactList}\item 
void \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause} \textbf{ cause}, void $\ast$\textbf{ data}, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em Terminate all child FSM instances of an FSM instance. \end{DoxyCompactList}\item 
void \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t \textbf{ event}, void $\ast$\textbf{ data}, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em Broadcast an event to all the FSMs children. \end{DoxyCompactList}\item 
\textbf{ LLIST\+\_\+\+HEAD} (\textbf{ osmo\+\_\+g\+\_\+fsms})
\item 
static void \textbf{ fsm\+\_\+free\+\_\+or\+\_\+steal} (void $\ast$talloc\+\_\+object)
\begin{DoxyCompactList}\small\item\em Internal call to free an FSM instance, which redirects to the context set by \doxyref{osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx()}{p.}{group__fsm_gaf031d280ac7d4fc8ac17e8560e5370a8} if any. \end{DoxyCompactList}\item 
static void \textbf{ osmo\+\_\+fsm\+\_\+defer\+\_\+free} (void $\ast$talloc\+\_\+object)
\begin{DoxyCompactList}\small\item\em talloc\+\_\+free() the given object immediately, or once ongoing FSM terminations are done. \end{DoxyCompactList}\item 
static void \textbf{ fsm\+\_\+tmr\+\_\+cb} (void $\ast$\textbf{ data})
\item 
static void \textbf{ update\+\_\+name} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi)
\item 
static int \textbf{ state\+\_\+chg} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, bool keep\+\_\+timer, unsigned long timeout\+\_\+ms, int T, const char $\ast$\textbf{ file}, int line)
\end{DoxyCompactItemize}
\doxysubsection*{Variables}
\begin{DoxyCompactItemize}
\item 
const struct \textbf{ value\+\_\+string} \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+names} [$\,$]
\item 
static bool \textbf{ fsm\+\_\+log\+\_\+addr} = true
\item 
static bool \textbf{ fsm\+\_\+log\+\_\+timeouts} = false
\item 
static bool \textbf{ fsm\+\_\+term\+\_\+safely\+\_\+enabled} = false
\begin{DoxyCompactList}\small\item\em See \doxyref{osmo\+\_\+fsm\+\_\+term\+\_\+safely()}{p.}{group__fsm_ga7ae199b946d722bc789b1c59f7c3aa15}. \end{DoxyCompactList}\item 
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=xx\=xx\=xx\=xx\=\kill
struct \{\\
\>struct \textbf{ osmo\_fsm\_inst} $\ast$ \textbf{ root\_fi}\\
\>\>{\em The first FSM instance that invoked \doxyref{osmo\_fsm\_inst\_term()}{p.}{group__fsm_ga22397fdc69a4f1c303bb0b2694d5f2aa} in the current cascade. }\\
\>unsigned int \textbf{ depth}\\
\>\>{\em 2 if a secondary FSM terminates, 3 if a secondary FSM causes a tertiary FSM to terminate, and so on. }\\
\>void $\ast$ \textbf{ collect\_ctx}\\
\>\>{\em Talloc context to collect all deferred deallocations (FSM instances, and talloc objects if any). }\\
\>void $\ast$ \textbf{ fsm\_dealloc\_ctx}\\
\>\>{\em See \doxyref{osmo\_fsm\_set\_dealloc\_ctx()}{p.}{group__fsm_gaf031d280ac7d4fc8ac17e8560e5370a8} }\\
\} \textbf{ fsm\_term\_safely}\\

\end{tabbing}\begin{DoxyCompactList}\small\item\em Internal state for FSM instance termination cascades. \end{DoxyCompactList}\item 
const struct \textbf{ value\+\_\+string} \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+names} [$\,$]
\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Finite State Machine abstraction. 

This is a generic C-\/language abstraction for implementing finite state machines within the Osmocom framework. It is intended to replace existing hand-\/coded or even only implicitly existing FSMs all over the existing code base.

An libosmocore FSM is described by its \doxyref{osmo\+\_\+fsm}{p.}{structosmo__fsm} description, which in turn refers to an array of \doxyref{osmo\+\_\+fsm\+\_\+state}{p.}{structosmo__fsm__state} descriptor, each describing a single state in the FSM.

The general idea is that all actions performed within one state are located at one position in the code (the state\textquotesingle{}s action function), as opposed to the \textquotesingle{}message-\/centric\textquotesingle{} view of e.\+g. the existing state machines of the LAPD(m) core, where there is one message for each possible event (primitive), and the function then needs to concern itself on how to handle that event over all possible states.

For each state, there is a bit-\/mask of permitted input events for this state, as well as a bit-\/mask of permitted new output states to which the state can change. Furthermore, there is a function pointer implementing the actual handling of the input events occurring whilst in that state.

Furthermore, each state offers a function pointer that can be executed just before leaving a state, and another one just after entering a state.

When transitioning into a new state, an optional timer number and time-\/out can be passed along. The timer is started just after entering the new state, and will call the \doxyref{osmo\+\_\+fsm}{p.}{structosmo__fsm} timer\+\_\+cb function once it expires. This is intended to be used in telecom state machines where a given timer (identified by a certain number) is started to terminate the fsm or terminate the fsm once expected events are not happening before timeout expiration.

As there can often be many concurrent FSMs of one given class, we introduce the concept of \doxyref{osmo\+\_\+fsm\+\_\+inst}{p.}{structosmo__fsm__inst}, i.\+e. an FSM instance. The instance keeps the actual state, while the \doxyref{osmo\+\_\+fsm}{p.}{structosmo__fsm} descriptor contains the static/const descriptor of the FSM\textquotesingle{}s states and possible transitions.

\doxyref{osmo\+\_\+fsm}{p.}{structosmo__fsm} are integrated with the libosmocore logging system. The logging sub-\/system is determined by the FSM descriptor, as we assume one FSM (let\textquotesingle{}s say one related to a location update procedure) is inevitably always tied to a sub-\/system. The logging level however is configurable for each FSM instance, to ensure that e.\+g. DEBUG logging can be used for the LU procedure of one subscriber, while NOTICE level is used for all other subscribers.

In order to attach private state to the \doxyref{osmo\+\_\+fsm\+\_\+inst}{p.}{structosmo__fsm__inst}, it offers an opaque private pointer. 

\doxysubsection{Macro Definition Documentation}
\mbox{\label{group__fsm_ga66da89c33fe5a79d4672674125ebbff3}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!LOGPFSM@{LOGPFSM}}
\index{LOGPFSM@{LOGPFSM}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{LOGPFSM}
{\footnotesize\ttfamily \#define LOGPFSM(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{fmt,  }\item[{}]{args... }\end{DoxyParamCaption})~  \textbf{ LOGPFSML}(fi, (fi) ? (fi)-\/$>$log\+\_\+level \+: \textbf{ LOGL\+\_\+\+ERROR}, fmt, \#\# args)}



Log using FSM instance\textquotesingle{}s context. 

The log level to log on is obtained from the FSM instance. The log subsystem to log on is obtained from the underlying FSM definition. 
\begin{DoxyParams}{Parameters}
{\em fi} & An \doxyref{osmo\+\_\+fsm\+\_\+inst}{p.}{structosmo__fsm__inst}. \\
\hline
{\em fmt} & printf-\/like format string. \\
\hline
{\em args} & Format string arguments. \\
\hline
\end{DoxyParams}
\mbox{\label{group__fsm_ga248ade15a1d1ff4f70788ef38e8b6245}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!LOGPFSML@{LOGPFSML}}
\index{LOGPFSML@{LOGPFSML}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{LOGPFSML}
{\footnotesize\ttfamily \#define LOGPFSML(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{\textbf{ level},  }\item[{}]{fmt,  }\item[{}]{args... }\end{DoxyParamCaption})~  \textbf{ LOGPFSMLSRC}(fi, \textbf{ level}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+, fmt, \#\# args)}



Log using FSM instance\textquotesingle{}s context, on explicit logging level. 


\begin{DoxyParams}{Parameters}
{\em fi} & An \doxyref{osmo\+\_\+fsm\+\_\+inst}{p.}{structosmo__fsm__inst}. \\
\hline
{\em level} & A logging level, e.\+g. LOGL\+\_\+\+INFO. \\
\hline
{\em fmt} & printf-\/like format string. \\
\hline
{\em args} & Format string arguments. \\
\hline
\end{DoxyParams}
\mbox{\label{group__fsm_gaaf05b1a8f42eb3f914af695c4d87a770}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!LOGPFSMLSRC@{LOGPFSMLSRC}}
\index{LOGPFSMLSRC@{LOGPFSMLSRC}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{LOGPFSMLSRC}
{\footnotesize\ttfamily \#define LOGPFSMLSRC(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{\textbf{ level},  }\item[{}]{caller\+\_\+file,  }\item[{}]{caller\+\_\+line,  }\item[{}]{fmt,  }\item[{}]{args... }\end{DoxyParamCaption})}

{\bfseries Value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{                LOGPFSMSLSRC(fi, (fi) ? (fi)-\/>fsm-\/>log\_subsys : DLGLOBAL, level, \(\backslash\)}
\DoxyCodeLine{                             caller\_file, caller\_line, fmt, \#\# args)}

\end{DoxyCode}


Log using FSM instance\textquotesingle{}s context, on explicit logging level, and with explicit source file and line info. 

The log subsystem to log on is obtained from the underlying FSM definition. 
\begin{DoxyParams}{Parameters}
{\em fi} & An \doxyref{osmo\+\_\+fsm\+\_\+inst}{p.}{structosmo__fsm__inst}. \\
\hline
{\em level} & A logging level, e.\+g. LOGL\+\_\+\+INFO. \\
\hline
{\em caller\+\_\+file} & A string constant containing a source file path, like {\bfseries{FILE}}. \\
\hline
{\em caller\+\_\+line} & A number constant containing a source file line, like {\bfseries{LINE}}. \\
\hline
{\em fmt} & printf-\/like format string. \\
\hline
{\em args} & Format string arguments. \\
\hline
\end{DoxyParams}
\mbox{\label{group__fsm_ga6f501668d6d818fc87f1b18425356b19}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!LOGPFSMSL@{LOGPFSMSL}}
\index{LOGPFSMSL@{LOGPFSMSL}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{LOGPFSMSL}
{\footnotesize\ttfamily \#define LOGPFSMSL(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{\textbf{ subsys},  }\item[{}]{\textbf{ level},  }\item[{}]{fmt,  }\item[{}]{args... }\end{DoxyParamCaption})~  \textbf{ LOGPFSMSLSRC}(fi, \textbf{ subsys}, \textbf{ level}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+, fmt, \#\# args)}



Log using FSM instance\textquotesingle{}s context, on explicit logging subsystem and level. 


\begin{DoxyParams}{Parameters}
{\em fi} & An \doxyref{osmo\+\_\+fsm\+\_\+inst}{p.}{structosmo__fsm__inst}. \\
\hline
{\em subsys} & A logging subsystem, e.\+g. DLGLOBAL. \\
\hline
{\em level} & A logging level, e.\+g. LOGL\+\_\+\+INFO. \\
\hline
{\em fmt} & printf-\/like format string. \\
\hline
{\em args} & Format string arguments. \\
\hline
\end{DoxyParams}
\mbox{\label{group__fsm_ga9f0a5bfa21b49696349ed9dd7dad8af1}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!LOGPFSMSLSRC@{LOGPFSMSLSRC}}
\index{LOGPFSMSLSRC@{LOGPFSMSLSRC}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{LOGPFSMSLSRC}
{\footnotesize\ttfamily \#define LOGPFSMSLSRC(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{\textbf{ subsys},  }\item[{}]{\textbf{ level},  }\item[{}]{caller\+\_\+file,  }\item[{}]{caller\+\_\+line,  }\item[{}]{fmt,  }\item[{}]{args... }\end{DoxyParamCaption})}

{\bfseries Value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{                LOGPSRC(subsys, level, \(\backslash\)}
\DoxyCodeLine{                        caller\_file, caller\_line, \(\backslash\)}
\DoxyCodeLine{                        \textcolor{stringliteral}{"{}\%s\{\%s\}: "{}} fmt, \(\backslash\)}
\DoxyCodeLine{                        osmo\_fsm\_inst\_name(fi), \(\backslash\)}
\DoxyCodeLine{                        (fi) ? osmo\_fsm\_state\_name((fi)-\/>fsm, (fi)-\/>state) : \textcolor{stringliteral}{"{}fi=NULL"{}}, \#\# args)}

\end{DoxyCode}


Log using FSM instance\textquotesingle{}s context, on explicit logging subsystem and level, and passing explicit source file and line information. 


\begin{DoxyParams}{Parameters}
{\em fi} & An \doxyref{osmo\+\_\+fsm\+\_\+inst}{p.}{structosmo__fsm__inst}. \\
\hline
{\em subsys} & A logging subsystem, e.\+g. DLGLOBAL. \\
\hline
{\em level} & A logging level, e.\+g. LOGL\+\_\+\+INFO. \\
\hline
{\em caller\+\_\+file} & A string constant containing a source file path, like {\bfseries{FILE}}. \\
\hline
{\em caller\+\_\+line} & A number constant containing a source file line, like {\bfseries{LINE}}. \\
\hline
{\em fmt} & printf-\/like format string. \\
\hline
{\em args} & Format string arguments. \\
\hline
\end{DoxyParams}
\mbox{\label{group__fsm_ga366288002411697a3687219b66c8f2e4}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!LOGPFSMSRC@{LOGPFSMSRC}}
\index{LOGPFSMSRC@{LOGPFSMSRC}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{LOGPFSMSRC}
{\footnotesize\ttfamily \#define LOGPFSMSRC(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{caller\+\_\+file,  }\item[{}]{caller\+\_\+line,  }\item[{}]{fmt,  }\item[{}]{args... }\end{DoxyParamCaption})}

{\bfseries Value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{                LOGPFSMLSRC(fi, (fi) ? (fi)-\/>log\_level : LOGL\_ERROR, \(\backslash\)}
\DoxyCodeLine{                            caller\_file, caller\_line, \(\backslash\)}
\DoxyCodeLine{                            fmt, \#\# args)}

\end{DoxyCode}


Log using FSM instance\textquotesingle{}s context, with explicit source file and line info. 

The log level to log on is obtained from the FSM instance. The log subsystem to log on is obtained from the underlying FSM definition. 
\begin{DoxyParams}{Parameters}
{\em fi} & An \doxyref{osmo\+\_\+fsm\+\_\+inst}{p.}{structosmo__fsm__inst}. \\
\hline
{\em caller\+\_\+file} & A string constant containing a source file path, like {\bfseries{FILE}}. \\
\hline
{\em caller\+\_\+line} & A number constant containing a source file line, like {\bfseries{LINE}}. \\
\hline
{\em fmt} & printf-\/like format string. \\
\hline
{\em args} & Format string arguments. \\
\hline
\end{DoxyParams}
\mbox{\label{group__fsm_gacd75fb4de417fb951b17bba2a554c877}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_broadcast\_children@{osmo\_fsm\_inst\_broadcast\_children}}
\index{osmo\_fsm\_inst\_broadcast\_children@{osmo\_fsm\_inst\_broadcast\_children}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_broadcast\_children}
{\footnotesize\ttfamily \#define osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{\textbf{ cause},  }\item[{}]{\textbf{ data} }\end{DoxyParamCaption})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children}(fi, \textbf{ cause}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)}



dispatch an event to all children of an osmocom finite state machine instance 

This is a macro that calls \doxyref{\+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children()}{p.}{group__fsm_ga4ec2d59ba8fa1effca075762cde6156b} with the given parameters as well as the caller\textquotesingle{}s source file and line number for logging purposes. See there for documentation. \mbox{\label{group__fsm_ga75d93c070baff6dd6e555d91a7ccc62f}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_dispatch@{osmo\_fsm\_inst\_dispatch}}
\index{osmo\_fsm\_inst\_dispatch@{osmo\_fsm\_inst\_dispatch}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_dispatch}
{\footnotesize\ttfamily \#define osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{\textbf{ event},  }\item[{}]{\textbf{ data} }\end{DoxyParamCaption})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch}(fi, \textbf{ event}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)}



dispatch an event to an osmocom finite state machine instance 

This is a macro that calls \doxyref{\+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch()}{p.}{group__fsm_ga523a1a8428c37cb1d30fa1c3c11e6db1} with the given parameters as well as the caller\textquotesingle{}s source file and line number for logging purposes. See there for documentation. \mbox{\label{group__fsm_gac2bc3009053763ca99356e824529a2e4}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_state\_chg@{osmo\_fsm\_inst\_state\_chg}}
\index{osmo\_fsm\_inst\_state\_chg@{osmo\_fsm\_inst\_state\_chg}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_state\_chg}
{\footnotesize\ttfamily \#define osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{new\+\_\+state,  }\item[{}]{timeout\+\_\+secs,  }\item[{}]{T }\end{DoxyParamCaption})}

{\bfseries Value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{        \_osmo\_fsm\_inst\_state\_chg(fi, new\_state, timeout\_secs, T, \(\backslash\)}
\DoxyCodeLine{                                 \_\_FILE\_\_, \_\_LINE\_\_)}

\end{DoxyCode}


perform a state change of the given FSM instance 

This is a macro that calls \doxyref{\+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg()}{p.}{group__fsm_ga7608be014cba6f4310e880481b309a94} with the given parameters as well as the caller\textquotesingle{}s source file and line number for logging purposes. See there for documentation. \mbox{\label{group__fsm_gacb4924436f161531a6dd319b63a44878}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer@{osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer}}
\index{osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer@{osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer}
{\footnotesize\ttfamily \#define osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{new\+\_\+state,  }\item[{}]{timeout\+\_\+secs,  }\item[{}]{T }\end{DoxyParamCaption})}

{\bfseries Value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{        \_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer(fi, new\_state, timeout\_secs, T, \(\backslash\)}
\DoxyCodeLine{                                                     \_\_FILE\_\_, \_\_LINE\_\_)}

\end{DoxyCode}


perform a state change while keeping the current timer if running, or starting a timer otherwise. 

This is useful to keep a timeout across several states, but to make sure that some timeout is actually running.

This is a macro that calls \doxyref{\+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer()}{p.}{group__fsm_ga159227b2c4b5ee4bb668e3460adf7c47} with the given parameters as well as the caller\textquotesingle{}s source file and line number for logging purposes. See there for documentation. \mbox{\label{group__fsm_gabaa3b0fde0c5b1993deb078374f84ffc}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms@{osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms}}
\index{osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms@{osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms}
{\footnotesize\ttfamily \#define osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer\+\_\+ms(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{new\+\_\+state,  }\item[{}]{timeout\+\_\+ms,  }\item[{}]{T }\end{DoxyParamCaption})}

{\bfseries Value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{        \_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms(fi, new\_state, timeout\_ms, T, \(\backslash\)}
\DoxyCodeLine{                                                     \_\_FILE\_\_, \_\_LINE\_\_)}

\end{DoxyCode}
\mbox{\label{group__fsm_ga605785659c0482d32c83748f88904ace}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_state\_chg\_keep\_timer@{osmo\_fsm\_inst\_state\_chg\_keep\_timer}}
\index{osmo\_fsm\_inst\_state\_chg\_keep\_timer@{osmo\_fsm\_inst\_state\_chg\_keep\_timer}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_state\_chg\_keep\_timer}
{\footnotesize\ttfamily \#define osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{new\+\_\+state }\end{DoxyParamCaption})}

{\bfseries Value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{        \_osmo\_fsm\_inst\_state\_chg\_keep\_timer(fi, new\_state, \(\backslash\)}
\DoxyCodeLine{                                 \_\_FILE\_\_, \_\_LINE\_\_)}

\end{DoxyCode}


perform a state change while keeping the current timer running. 

This is useful to keep a timeout across several states (without having to round the remaining time to seconds).

This is a macro that calls \doxyref{\+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer()}{p.}{group__fsm_gaa8eef574f84a42c60ce12646b0618e0e} with the given parameters as well as the caller\textquotesingle{}s source file and line number for logging purposes. See there for documentation. \mbox{\label{group__fsm_ga06bd66dd40203f72953962be8e4e58cb}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_state\_chg\_ms@{osmo\_fsm\_inst\_state\_chg\_ms}}
\index{osmo\_fsm\_inst\_state\_chg\_ms@{osmo\_fsm\_inst\_state\_chg\_ms}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_state\_chg\_ms}
{\footnotesize\ttfamily \#define osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+ms(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{new\+\_\+state,  }\item[{}]{timeout\+\_\+ms,  }\item[{}]{T }\end{DoxyParamCaption})}

{\bfseries Value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{        \_osmo\_fsm\_inst\_state\_chg\_ms(fi, new\_state, timeout\_ms, T, \(\backslash\)}
\DoxyCodeLine{                                 \_\_FILE\_\_, \_\_LINE\_\_)}

\end{DoxyCode}
\mbox{\label{group__fsm_ga22397fdc69a4f1c303bb0b2694d5f2aa}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_term@{osmo\_fsm\_inst\_term}}
\index{osmo\_fsm\_inst\_term@{osmo\_fsm\_inst\_term}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_term}
{\footnotesize\ttfamily \#define osmo\+\_\+fsm\+\_\+inst\+\_\+term(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{\textbf{ cause},  }\item[{}]{\textbf{ data} }\end{DoxyParamCaption})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term}(fi, \textbf{ cause}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)}



Terminate FSM instance with given cause. 

This is a macro that calls \doxyref{\+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term()}{p.}{group__fsm_ga9b46a56e04ac98b7f20cae167e952a12} with the given parameters as well as the caller\textquotesingle{}s source file and line number for logging purposes. See there for documentation. \mbox{\label{group__fsm_ga73462b9dcd7c5e33186e3319672045d1}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_term\_children@{osmo\_fsm\_inst\_term\_children}}
\index{osmo\_fsm\_inst\_term\_children@{osmo\_fsm\_inst\_term\_children}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_term\_children}
{\footnotesize\ttfamily \#define osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children(\begin{DoxyParamCaption}\item[{}]{fi,  }\item[{}]{\textbf{ cause},  }\item[{}]{\textbf{ data} }\end{DoxyParamCaption})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children}(fi, \textbf{ cause}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)}



Terminate all child FSM instances of an FSM instance. 

This is a macro that calls \doxyref{\+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children()}{p.}{group__fsm_ga2d5fc607d8297c048af8ae7f3e9a6ac8} with the given parameters as well as the caller\textquotesingle{}s source file and line number for logging purposes. See there for documentation. \mbox{\label{group__fsm_ga0eea157837d423a623cfecd581c24de3}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!OSMO\_T\_FMT@{OSMO\_T\_FMT}}
\index{OSMO\_T\_FMT@{OSMO\_T\_FMT}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{OSMO\_T\_FMT}
{\footnotesize\ttfamily \#define OSMO\+\_\+\+T\+\_\+\+FMT~\char`\"{}\%c\%\textbf{ u}\char`\"{}}

\mbox{\label{group__fsm_ga2f012bcf729f8788d21db8c11f755d51}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!OSMO\_T\_FMT\_ARGS@{OSMO\_T\_FMT\_ARGS}}
\index{OSMO\_T\_FMT\_ARGS@{OSMO\_T\_FMT\_ARGS}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{OSMO\_T\_FMT\_ARGS}
{\footnotesize\ttfamily \#define OSMO\+\_\+\+T\+\_\+\+FMT\+\_\+\+ARGS(\begin{DoxyParamCaption}\item[{}]{T }\end{DoxyParamCaption})~((T) $>$= 0 ? \textquotesingle{}T\textquotesingle{} \+: \textquotesingle{}X\textquotesingle{}), ((T) $>$= 0 ? (T) \+: -\/(T))}



\doxysubsection{Enumeration Type Documentation}
\mbox{\label{group__fsm_ga1c5b754d5fcf2bfe2f8bf4d4afedb413}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_term\_cause@{osmo\_fsm\_term\_cause}}
\index{osmo\_fsm\_term\_cause@{osmo\_fsm\_term\_cause}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_term\_cause}
{\footnotesize\ttfamily enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause}}

\begin{DoxyEnumFields}{Enumerator}
\raisebox{\heightof{T}}[0pt][0pt]{\index{OSMO\_FSM\_TERM\_PARENT@{OSMO\_FSM\_TERM\_PARENT}!Finite State Machine abstraction@{Finite State Machine abstraction}}\index{Finite State Machine abstraction@{Finite State Machine abstraction}!OSMO\_FSM\_TERM\_PARENT@{OSMO\_FSM\_TERM\_PARENT}}}\mbox{\label{group__fsm_gga1c5b754d5fcf2bfe2f8bf4d4afedb413ab30c67e0d20e1f8c7c28ddd3a20eef9e}} 
OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+PARENT&terminate because parent terminated \\
\hline

\raisebox{\heightof{T}}[0pt][0pt]{\index{OSMO\_FSM\_TERM\_REQUEST@{OSMO\_FSM\_TERM\_REQUEST}!Finite State Machine abstraction@{Finite State Machine abstraction}}\index{Finite State Machine abstraction@{Finite State Machine abstraction}!OSMO\_FSM\_TERM\_REQUEST@{OSMO\_FSM\_TERM\_REQUEST}}}\mbox{\label{group__fsm_gga1c5b754d5fcf2bfe2f8bf4d4afedb413a3202db525e55bc84276bf4e6aa7fcdd4}} 
OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+REQUEST&terminate on explicit user request \\
\hline

\raisebox{\heightof{T}}[0pt][0pt]{\index{OSMO\_FSM\_TERM\_REGULAR@{OSMO\_FSM\_TERM\_REGULAR}!Finite State Machine abstraction@{Finite State Machine abstraction}}\index{Finite State Machine abstraction@{Finite State Machine abstraction}!OSMO\_FSM\_TERM\_REGULAR@{OSMO\_FSM\_TERM\_REGULAR}}}\mbox{\label{group__fsm_gga1c5b754d5fcf2bfe2f8bf4d4afedb413aa5b1f64cc6be12a3d4e8d5c92ec068bd}} 
OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+REGULAR&regular termination of process \\
\hline

\raisebox{\heightof{T}}[0pt][0pt]{\index{OSMO\_FSM\_TERM\_ERROR@{OSMO\_FSM\_TERM\_ERROR}!Finite State Machine abstraction@{Finite State Machine abstraction}}\index{Finite State Machine abstraction@{Finite State Machine abstraction}!OSMO\_FSM\_TERM\_ERROR@{OSMO\_FSM\_TERM\_ERROR}}}\mbox{\label{group__fsm_gga1c5b754d5fcf2bfe2f8bf4d4afedb413a7395c7e1bc2b1182bf3cfe2c529bd800}} 
OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+ERROR&erroneous termination of process \\
\hline

\raisebox{\heightof{T}}[0pt][0pt]{\index{OSMO\_FSM\_TERM\_TIMEOUT@{OSMO\_FSM\_TERM\_TIMEOUT}!Finite State Machine abstraction@{Finite State Machine abstraction}}\index{Finite State Machine abstraction@{Finite State Machine abstraction}!OSMO\_FSM\_TERM\_TIMEOUT@{OSMO\_FSM\_TERM\_TIMEOUT}}}\mbox{\label{group__fsm_gga1c5b754d5fcf2bfe2f8bf4d4afedb413a8de3cf5fe33fc38b5204577d73845cc1}} 
OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+TIMEOUT&termination due to time-\/out \\
\hline

\end{DoxyEnumFields}


\doxysubsection{Function Documentation}
\mbox{\label{group__fsm_ga4ec2d59ba8fa1effca075762cde6156b}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!\_osmo\_fsm\_inst\_broadcast\_children@{\_osmo\_fsm\_inst\_broadcast\_children}}
\index{\_osmo\_fsm\_inst\_broadcast\_children@{\_osmo\_fsm\_inst\_broadcast\_children}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{\_osmo\_fsm\_inst\_broadcast\_children()}
{\footnotesize\ttfamily void \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{uint32\+\_\+t}]{event,  }\item[{void $\ast$}]{data,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})}



Broadcast an event to all the FSMs children. 

Iterate over all children and send them the specified event.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance of the parent \\
\hline
\mbox{\texttt{ in}}  & {\em event} & Event to send to children of FSM instance \\
\hline
\mbox{\texttt{ in}}  & {\em data} & Data to pass along with the event \\
\hline
\mbox{\texttt{ in}}  & {\em file} & Calling source file (from osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch macro) \\
\hline
\mbox{\texttt{ in}}  & {\em line} & Calling source line (from osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch macro) \\
\hline
\end{DoxyParams}


References \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::child}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::children}, \textbf{ data}, \textbf{ file()}, \textbf{ llist\+\_\+for\+\_\+each\+\_\+entry\+\_\+safe}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::proc}.

\mbox{\label{group__fsm_ga523a1a8428c37cb1d30fa1c3c11e6db1}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!\_osmo\_fsm\_inst\_dispatch@{\_osmo\_fsm\_inst\_dispatch}}
\index{\_osmo\_fsm\_inst\_dispatch@{\_osmo\_fsm\_inst\_dispatch}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{\_osmo\_fsm\_inst\_dispatch()}
{\footnotesize\ttfamily int \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{uint32\+\_\+t}]{event,  }\item[{void $\ast$}]{data,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})}



dispatch an event to an osmocom finite state machine instance 

Best invoke via the \doxyref{osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch()}{p.}{group__fsm_ga75d93c070baff6dd6e555d91a7ccc62f} macro which logs the source file where the event was effected. Alternatively, you may pass {\itshape file} as NULL to use the normal file/line indication instead.

Any incoming events to \doxyref{osmo\+\_\+fsm}{p.}{structosmo__fsm} instances must be dispatched to them via this function. It verifies, whether the event is permitted based on the current state of the FSM. If not, -\/1 is returned.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance \\
\hline
\mbox{\texttt{ in}}  & {\em event} & Event to send to FSM instance \\
\hline
\mbox{\texttt{ in}}  & {\em data} & Data to pass along with the event \\
\hline
\mbox{\texttt{ in}}  & {\em file} & Calling source file (from osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch macro) \\
\hline
\mbox{\texttt{ in}}  & {\em line} & Calling source line (from osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch macro) \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 in case of success; negative on error 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+fsm\+\_\+state\+::action}, \textbf{ osmo\+\_\+fsm\+::allstate\+\_\+action}, \textbf{ osmo\+\_\+fsm\+::allstate\+\_\+event\+\_\+mask}, \textbf{ data}, \textbf{ DLGLOBAL}, \textbf{ file()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ osmo\+\_\+fsm\+\_\+state\+::in\+\_\+event\+\_\+mask}, \textbf{ LOGL\+\_\+\+ERROR}, \textbf{ LOGPFSMLSRC}, \textbf{ LOGPFSMSRC}, \textbf{ LOGPSRC}, \textbf{ osmo\+\_\+fsm\+::num\+\_\+states}, \textbf{ OSMO\+\_\+\+ASSERT}, \textbf{ osmo\+\_\+fsm\+\_\+event\+\_\+name()}, \textbf{ osmo\+\_\+log\+\_\+backtrace()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::proc}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::state}, \textbf{ osmo\+\_\+fsm\+::states}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::terminating}.



Referenced by \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children()}, and \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term()}.

\mbox{\label{group__fsm_ga7608be014cba6f4310e880481b309a94}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!\_osmo\_fsm\_inst\_state\_chg@{\_osmo\_fsm\_inst\_state\_chg}}
\index{\_osmo\_fsm\_inst\_state\_chg@{\_osmo\_fsm\_inst\_state\_chg}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{\_osmo\_fsm\_inst\_state\_chg()}
{\footnotesize\ttfamily int \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{uint32\+\_\+t}]{new\+\_\+state,  }\item[{unsigned long}]{timeout\+\_\+secs,  }\item[{int}]{T,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})}



perform a state change of the given FSM instance 

Best invoke via the \doxyref{osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg()}{p.}{group__fsm_gac2bc3009053763ca99356e824529a2e4} macro which logs the source file where the state change was effected. Alternatively, you may pass {\itshape file} as NULL to use the normal file/line indication instead.

All changes to the FSM instance state must be made via an osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+$\ast$ function. It verifies that the existing state actually permits a transition to new\+\_\+state.

If timeout\+\_\+secs is 0, stay in the new state indefinitely, without a timeout (stop the FSM instance\textquotesingle{}s timer if it was runnning).

If timeout\+\_\+secs $>$ 0, start or reset the FSM instance\textquotesingle{}s timer with this timeout. On expiry, invoke the FSM instance\textquotesingle{}s timer\+\_\+cb -- if no timer\+\_\+cb is set, an expired timer immediately terminates the FSM instance with OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+TIMEOUT.

The value of T is stored in fi-\/$>$T and is then available for query in timer\+\_\+cb. If passing timeout\+\_\+secs == 0, it is recommended to also pass T == 0, so that fi-\/$>$T is reset to 0 when no timeout is invoked.

Positive values for T are considered to be 3GPP spec compliant and appear in logging and VTY as \char`\"{}\+T1234\char`\"{}, while negative values are considered to be Osmocom specific timers, represented in logging and VTY as \char`\"{}\+X1234\char`\"{}.

See also \doxyref{osmo\+\_\+tdef\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg()}{p.}{group__Tdef_ga62ef360585a2162bcac01c588025ce97} from the \doxyref{osmo\+\_\+tdef}{p.}{structosmo__tdef} API, which provides a unified way to configure and apply GSM style Tnnnn timers to FSM state transitions.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance whose state is to change \\
\hline
\mbox{\texttt{ in}}  & {\em new\+\_\+state} & The new state into which we should change \\
\hline
\mbox{\texttt{ in}}  & {\em timeout\+\_\+secs} & Timeout in seconds (if !=0), maximum-\/clamped to 2147483647 seconds. \\
\hline
\mbox{\texttt{ in}}  & {\em T} & Timer number, where positive numbers are considered to be 3GPP spec compliant timer numbers and are logged as \char`\"{}\+T1234\char`\"{}, while negative numbers are considered Osmocom specific timer numbers logged as \char`\"{}\+X1234\char`\"{}. \\
\hline
\mbox{\texttt{ in}}  & {\em file} & Calling source file (from osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg macro) \\
\hline
\mbox{\texttt{ in}}  & {\em line} & Calling source line (from osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg macro) \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 on success; negative on error 
\end{DoxyReturn}


References \textbf{ file()}, and \textbf{ state\+\_\+chg()}.



Referenced by \textbf{ \+\_\+osmo\+\_\+tdef\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg()}.

\mbox{\label{group__fsm_ga159227b2c4b5ee4bb668e3460adf7c47}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!\_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer@{\_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer}}
\index{\_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer@{\_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{\_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer()}
{\footnotesize\ttfamily int \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{uint32\+\_\+t}]{new\+\_\+state,  }\item[{unsigned long}]{timeout\+\_\+secs,  }\item[{int}]{T,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})}



perform a state change while keeping the current timer if running, or starting a timer otherwise. 

This is useful to keep a timeout across several states, but to make sure that some timeout is actually running.

Best invoke via the \doxyref{osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer()}{p.}{group__fsm_gacb4924436f161531a6dd319b63a44878} macro which logs the source file where the state change was effected. Alternatively, you may pass file as NULL to use the normal file/line indication instead.

All changes to the FSM instance state must be made via an osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+$\ast$ function. It verifies that the existing state actually permits a transition to new\+\_\+state.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance whose state is to change \\
\hline
\mbox{\texttt{ in}}  & {\em new\+\_\+state} & The new state into which we should change \\
\hline
\mbox{\texttt{ in}}  & {\em timeout\+\_\+secs} & If no timer is running yet, set this timeout in seconds (if !=0), maximum-\/clamped to 2147483647 seconds. \\
\hline
\mbox{\texttt{ in}}  & {\em T} & Timer number, where positive numbers are considered to be 3GPP spec compliant timer numbers and are logged as \char`\"{}\+T1234\char`\"{}, while negative numbers are considered Osmocom specific timer numbers logged as \char`\"{}\+X1234\char`\"{}. \\
\hline
\mbox{\texttt{ in}}  & {\em file} & Calling source file (from osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg macro) \\
\hline
\mbox{\texttt{ in}}  & {\em line} & Calling source line (from osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg macro) \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 on success; negative on error 
\end{DoxyReturn}


References \textbf{ file()}, and \textbf{ state\+\_\+chg()}.

\mbox{\label{group__fsm_ga423b10042103cfa1e0ec3713e3d477a8}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!\_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms@{\_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms}}
\index{\_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms@{\_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{\_osmo\_fsm\_inst\_state\_chg\_keep\_or\_start\_timer\_ms()}
{\footnotesize\ttfamily int \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer\+\_\+ms (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{uint32\+\_\+t}]{new\+\_\+state,  }\item[{unsigned long}]{timeout\+\_\+ms,  }\item[{int}]{T,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})}



References \textbf{ file()}, and \textbf{ state\+\_\+chg()}.



Referenced by \textbf{ \+\_\+osmo\+\_\+tdef\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg()}.

\mbox{\label{group__fsm_gaa8eef574f84a42c60ce12646b0618e0e}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!\_osmo\_fsm\_inst\_state\_chg\_keep\_timer@{\_osmo\_fsm\_inst\_state\_chg\_keep\_timer}}
\index{\_osmo\_fsm\_inst\_state\_chg\_keep\_timer@{\_osmo\_fsm\_inst\_state\_chg\_keep\_timer}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{\_osmo\_fsm\_inst\_state\_chg\_keep\_timer()}
{\footnotesize\ttfamily int \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{uint32\+\_\+t}]{new\+\_\+state,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})}



perform a state change while keeping the current timer running. 

This is useful to keep a timeout across several states (without having to round the remaining time to seconds).

Best invoke via the \doxyref{osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer()}{p.}{group__fsm_ga605785659c0482d32c83748f88904ace} macro which logs the source file where the state change was effected. Alternatively, you may pass {\itshape file} as NULL to use the normal file/line indication instead.

All changes to the FSM instance state must be made via an osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+$\ast$ function. It verifies that the existing state actually permits a transition to new\+\_\+state.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance whose state is to change \\
\hline
\mbox{\texttt{ in}}  & {\em new\+\_\+state} & The new state into which we should change \\
\hline
\mbox{\texttt{ in}}  & {\em file} & Calling source file (from osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg macro) \\
\hline
\mbox{\texttt{ in}}  & {\em line} & Calling source line (from osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg macro) \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 on success; negative on error 
\end{DoxyReturn}


References \textbf{ file()}, and \textbf{ state\+\_\+chg()}.



Referenced by \textbf{ \+\_\+osmo\+\_\+tdef\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg()}.

\mbox{\label{group__fsm_ga0a7ae7d6b80ea6e0123a78a850474f02}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!\_osmo\_fsm\_inst\_state\_chg\_ms@{\_osmo\_fsm\_inst\_state\_chg\_ms}}
\index{\_osmo\_fsm\_inst\_state\_chg\_ms@{\_osmo\_fsm\_inst\_state\_chg\_ms}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{\_osmo\_fsm\_inst\_state\_chg\_ms()}
{\footnotesize\ttfamily int \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+ms (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{uint32\+\_\+t}]{new\+\_\+state,  }\item[{unsigned long}]{timeout\+\_\+ms,  }\item[{int}]{T,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})}



References \textbf{ file()}, and \textbf{ state\+\_\+chg()}.



Referenced by \textbf{ \+\_\+osmo\+\_\+tdef\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg()}.

\mbox{\label{group__fsm_ga9b46a56e04ac98b7f20cae167e952a12}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!\_osmo\_fsm\_inst\_term@{\_osmo\_fsm\_inst\_term}}
\index{\_osmo\_fsm\_inst\_term@{\_osmo\_fsm\_inst\_term}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{\_osmo\_fsm\_inst\_term()}
{\footnotesize\ttfamily void \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause}}]{cause,  }\item[{void $\ast$}]{data,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})}



Terminate FSM instance with given cause. 

This safely terminates the given FSM instance by first iterating over all children and sending them a termination event. Next, it calls the FSM descriptors cleanup function (if any), followed by releasing any memory associated with the FSM instance.

Finally, the parent FSM instance (if any) is notified using the parent termination event configured at time of FSM instance start.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance to be terminated \\
\hline
\mbox{\texttt{ in}}  & {\em cause} & Cause / reason for termination \\
\hline
\mbox{\texttt{ in}}  & {\em data} & Opaque event data to be passed with the parent term event \\
\hline
\mbox{\texttt{ in}}  & {\em file} & Calling source file (from osmo\+\_\+fsm\+\_\+inst\+\_\+term macro) \\
\hline
\mbox{\texttt{ in}}  & {\em line} & Calling source line (from osmo\+\_\+fsm\+\_\+inst\+\_\+term macro) \\
\hline
\end{DoxyParams}


References \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch()}, \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children()}, \textbf{ cause}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::child}, \textbf{ osmo\+\_\+fsm\+::cleanup}, \textbf{ data}, \textbf{ file()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ fsm\+\_\+term\+\_\+safely}, \textbf{ fsm\+\_\+term\+\_\+safely\+\_\+enabled}, \textbf{ llist\+\_\+del()}, \textbf{ LOGPFSMSRC}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+free()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+name()}, \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+name()}, \textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+PARENT}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::parent}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::parent\+\_\+term\+\_\+event}, \textbf{ osmo\+\_\+fsm\+::pre\+\_\+term}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::proc}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::terminating}.



Referenced by \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children()}.

\mbox{\label{group__fsm_ga2d5fc607d8297c048af8ae7f3e9a6ac8}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!\_osmo\_fsm\_inst\_term\_children@{\_osmo\_fsm\_inst\_term\_children}}
\index{\_osmo\_fsm\_inst\_term\_children@{\_osmo\_fsm\_inst\_term\_children}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{\_osmo\_fsm\_inst\_term\_children()}
{\footnotesize\ttfamily void \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause}}]{cause,  }\item[{void $\ast$}]{data,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})}



Terminate all child FSM instances of an FSM instance. 

Iterate over all children and send them a termination event, with the given cause. Pass OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+PARENT to avoid dispatching events from the terminated child FSMs.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance that should be cleared of child FSMs \\
\hline
\mbox{\texttt{ in}}  & {\em cause} & Cause / reason for termination (OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+PARENT) \\
\hline
\mbox{\texttt{ in}}  & {\em data} & Opaque event data to be passed with the parent term events \\
\hline
\mbox{\texttt{ in}}  & {\em file} & Calling source file (from osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children macro) \\
\hline
\mbox{\texttt{ in}}  & {\em line} & Calling source line (from osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children macro) \\
\hline
\end{DoxyParams}


References \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term()}, \textbf{ cause}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::children}, \textbf{ data}, \textbf{ file()}, \textbf{ llist\+\_\+empty()}, \textbf{ llist\+\_\+entry}, \textbf{ LOGL\+\_\+\+ERROR}, \textbf{ LOGPFSMLSRC}, \textbf{ llist\+\_\+head\+::next}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::proc}.



Referenced by \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term()}.

\mbox{\label{group__fsm_ga030dcf02919dfae0a95a13626f66f98d}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!fsm\_free\_or\_steal@{fsm\_free\_or\_steal}}
\index{fsm\_free\_or\_steal@{fsm\_free\_or\_steal}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{fsm\_free\_or\_steal()}
{\footnotesize\ttfamily static void fsm\+\_\+free\+\_\+or\+\_\+steal (\begin{DoxyParamCaption}\item[{void $\ast$}]{talloc\+\_\+object }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [static]}}



Internal call to free an FSM instance, which redirects to the context set by \doxyref{osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx()}{p.}{group__fsm_gaf031d280ac7d4fc8ac17e8560e5370a8} if any. 



References \textbf{ fsm\+\_\+term\+\_\+safely}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+defer\+\_\+free()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc()}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+free()}.

\mbox{\label{group__fsm_gadd6cf7d6e42ca941baaf5840a07922c8}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!fsm\_tmr\_cb@{fsm\_tmr\_cb}}
\index{fsm\_tmr\_cb@{fsm\_tmr\_cb}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{fsm\_tmr\_cb()}
{\footnotesize\ttfamily static void fsm\+\_\+tmr\+\_\+cb (\begin{DoxyParamCaption}\item[{void $\ast$}]{data }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [static]}}



References \textbf{ data}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ LOGPFSM}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+term}, \textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+TIMEOUT}, \textbf{ OSMO\+\_\+\+T\+\_\+\+FMT}, \textbf{ OSMO\+\_\+\+T\+\_\+\+FMT\+\_\+\+ARGS}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::T}, and \textbf{ osmo\+\_\+fsm\+::timer\+\_\+cb}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc()}.

\mbox{\label{group__fsm_ga899732f691814df3bf90f25bc7ff5a0b}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!LLIST\_HEAD@{LLIST\_HEAD}}
\index{LLIST\_HEAD@{LLIST\_HEAD}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{LLIST\_HEAD()}
{\footnotesize\ttfamily LLIST\+\_\+\+HEAD (\begin{DoxyParamCaption}\item[{\textbf{ osmo\+\_\+g\+\_\+fsms}}]{ }\end{DoxyParamCaption})}

\mbox{\label{group__fsm_ga4e180dcf9205a194dafffd7d3afa928a}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_defer\_free@{osmo\_fsm\_defer\_free}}
\index{osmo\_fsm\_defer\_free@{osmo\_fsm\_defer\_free}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_defer\_free()}
{\footnotesize\ttfamily static void osmo\+\_\+fsm\+\_\+defer\+\_\+free (\begin{DoxyParamCaption}\item[{void $\ast$}]{talloc\+\_\+object }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [static]}}



talloc\+\_\+free() the given object immediately, or once ongoing FSM terminations are done. 

If an FSM deallocation cascade is ongoing, talloc\+\_\+steal() the given talloc\+\_\+object into the talloc context that is freed once the cascade is done. If no FSM deallocation cascade is ongoing, or if \doxyref{osmo\+\_\+fsm\+\_\+term\+\_\+safely()}{p.}{group__fsm_ga7ae199b946d722bc789b1c59f7c3aa15} is disabled, immediately talloc\+\_\+free the object.

This can be useful if some higher order talloc object, which is the talloc parent for FSM instances or their priv objects, is not itself tied to an FSM instance. This function allows safely freeing it without affecting ongoing FSM termination cascades.

Once passed to this function, the talloc\+\_\+object should be considered as already freed. Only FSM instance pre\+\_\+term() and cleanup() functions as well as event handling caused by these may safely assume that it is still valid memory.

The talloc\+\_\+object should not have multiple parents.

(This function may some day move to public API, which might be redundant if we introduce a select-\/loop volatile context mechanism to defer deallocation instead.)


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em talloc\+\_\+object} & Object pointer to free. \\
\hline
\end{DoxyParams}


References \textbf{ fsm\+\_\+free\+\_\+or\+\_\+steal()}, \textbf{ fsm\+\_\+term\+\_\+safely}, and \textbf{ OSMO\+\_\+\+ASSERT}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+free()}.

\mbox{\label{group__fsm_ga242186790266b18531bb9fde93b2487d}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_event\_name@{osmo\_fsm\_event\_name}}
\index{osmo\_fsm\_event\_name@{osmo\_fsm\_event\_name}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_event\_name()}
{\footnotesize\ttfamily const char $\ast$ osmo\+\_\+fsm\+\_\+event\+\_\+name (\begin{DoxyParamCaption}\item[{const struct \textbf{ osmo\+\_\+fsm} $\ast$}]{fsm,  }\item[{uint32\+\_\+t}]{event }\end{DoxyParamCaption})}



get human-\/readable name of FSM event 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fsm} & FSM descriptor of event \\
\hline
\mbox{\texttt{ in}}  & {\em event} & Event integer value \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
string rendering of the event 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+fsm\+::event\+\_\+names}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, and \textbf{ get\+\_\+value\+\_\+string()}.



Referenced by \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch()}.

\mbox{\label{group__fsm_ga1e43eb41f84e07b9606c9cdcba87c6c2}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_find\_by\_name@{osmo\_fsm\_find\_by\_name}}
\index{osmo\_fsm\_find\_by\_name@{osmo\_fsm\_find\_by\_name}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_find\_by\_name()}
{\footnotesize\ttfamily struct \textbf{ osmo\+\_\+fsm} $\ast$ osmo\+\_\+fsm\+\_\+find\+\_\+by\+\_\+name (\begin{DoxyParamCaption}\item[{const char $\ast$}]{name }\end{DoxyParamCaption})}



References \textbf{ list}, \textbf{ llist\+\_\+for\+\_\+each\+\_\+entry}, \textbf{ name}, \textbf{ osmo\+\_\+fsm\+::name}, and \textbf{ osmo\+\_\+g\+\_\+fsms}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+register()}.

\mbox{\label{group__fsm_gab86e5e11480147ed8e39d9dd2a6884e5}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_alloc@{osmo\_fsm\_inst\_alloc}}
\index{osmo\_fsm\_inst\_alloc@{osmo\_fsm\_inst\_alloc}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_alloc()}
{\footnotesize\ttfamily struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm} $\ast$}]{fsm,  }\item[{void $\ast$}]{ctx,  }\item[{void $\ast$}]{priv,  }\item[{int}]{log\+\_\+level,  }\item[{const char $\ast$}]{id }\end{DoxyParamCaption})}



allocate a new instance of a specified FSM 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fsm} & Descriptor of the FSM \\
\hline
\mbox{\texttt{ in}}  & {\em ctx} & talloc context from which to allocate memory \\
\hline
\mbox{\texttt{ in}}  & {\em priv} & private data reference store in fsm instance \\
\hline
\mbox{\texttt{ in}}  & {\em log\+\_\+level} & The log level for events of this FSM \\
\hline
\mbox{\texttt{ in}}  & {\em id} & The name/\+ID of the FSM instance \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
newly-\/allocated, initialized and registered FSM instance 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::child}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::children}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ fsm\+\_\+free\+\_\+or\+\_\+steal()}, \textbf{ fsm\+\_\+tmr\+\_\+cb()}, \textbf{ INIT\+\_\+\+LLIST\+\_\+\+HEAD}, \textbf{ osmo\+\_\+fsm\+::instances}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::list}, \textbf{ llist\+\_\+add()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::log\+\_\+level}, \textbf{ LOGPFSM}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id()}, \textbf{ osmo\+\_\+timer\+\_\+setup()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::priv}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::proc}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::timer}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc\+\_\+child()}.

\mbox{\label{group__fsm_ga7fd84a05fb6fd849d46219730202e5d3}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_alloc\_child@{osmo\_fsm\_inst\_alloc\_child}}
\index{osmo\_fsm\_inst\_alloc\_child@{osmo\_fsm\_inst\_alloc\_child}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_alloc\_child()}
{\footnotesize\ttfamily struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc\+\_\+child (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm} $\ast$}]{fsm,  }\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{parent,  }\item[{uint32\+\_\+t}]{parent\+\_\+term\+\_\+event }\end{DoxyParamCaption})}



allocate a new instance of a specified FSM as child of other FSM instance 

This is like \doxyref{osmo\+\_\+fsm\+\_\+inst\+\_\+alloc}{p.}{group__fsm_gab86e5e11480147ed8e39d9dd2a6884e5} but using the parent FSM as talloc context, and inheriting the log level of the parent.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fsm} & Descriptor of the to-\/be-\/allocated FSM \\
\hline
\mbox{\texttt{ in}}  & {\em parent} & Parent FSM instance \\
\hline
\mbox{\texttt{ in}}  & {\em parent\+\_\+term\+\_\+event} & Event to be sent to parent when terminating \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
newly-\/allocated, initialized and registered FSM instance 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::id}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::log\+\_\+level}, \textbf{ LOGPFSM}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+change\+\_\+parent()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+name()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::parent}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::parent\+\_\+term\+\_\+event}.

\mbox{\label{group__fsm_ga4411b21a211cd81f2e858a146f2c4cca}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_change\_parent@{osmo\_fsm\_inst\_change\_parent}}
\index{osmo\_fsm\_inst\_change\_parent@{osmo\_fsm\_inst\_change\_parent}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_change\_parent()}
{\footnotesize\ttfamily void osmo\+\_\+fsm\+\_\+inst\+\_\+change\+\_\+parent (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{new\+\_\+parent,  }\item[{uint32\+\_\+t}]{new\+\_\+parent\+\_\+term\+\_\+event }\end{DoxyParamCaption})}



change parent instance of an FSM. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & Descriptor of the to-\/be-\/allocated FSM. \\
\hline
\mbox{\texttt{ in}}  & {\em new\+\_\+parent} & New parent FSM instance. \\
\hline
\mbox{\texttt{ in}}  & {\em new\+\_\+parent\+\_\+term\+\_\+event} & Event to be sent to parent when terminating.\\
\hline
\end{DoxyParams}
Never call this function from the cleanup callback! (see also \doxyref{osmo\+\_\+fsm\+\_\+inst\+\_\+unlink\+\_\+parent()}{p.}{group__fsm_ga7f88d5cf42077f32bc5cf667ca310d9d}). 

References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::child}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::children}, \textbf{ llist\+\_\+add()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+unlink\+\_\+parent()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::parent}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::parent\+\_\+term\+\_\+event}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::proc}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc\+\_\+child()}.

\mbox{\label{group__fsm_gaf4d7f891b0a2110daa84136b5ea8f540}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_find\_by\_id@{osmo\_fsm\_inst\_find\_by\_id}}
\index{osmo\_fsm\_inst\_find\_by\_id@{osmo\_fsm\_inst\_find\_by\_id}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_find\_by\_id()}
{\footnotesize\ttfamily struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ osmo\+\_\+fsm\+\_\+inst\+\_\+find\+\_\+by\+\_\+id (\begin{DoxyParamCaption}\item[{const struct \textbf{ osmo\+\_\+fsm} $\ast$}]{fsm,  }\item[{const char $\ast$}]{id }\end{DoxyParamCaption})}



References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::id}, \textbf{ osmo\+\_\+fsm\+::instances}, \textbf{ list}, and \textbf{ llist\+\_\+for\+\_\+each\+\_\+entry}.

\mbox{\label{group__fsm_gafce8ab2dfb4f98c6ecd2eb064aa48746}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_find\_by\_name@{osmo\_fsm\_inst\_find\_by\_name}}
\index{osmo\_fsm\_inst\_find\_by\_name@{osmo\_fsm\_inst\_find\_by\_name}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_find\_by\_name()}
{\footnotesize\ttfamily struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ osmo\+\_\+fsm\+\_\+inst\+\_\+find\+\_\+by\+\_\+name (\begin{DoxyParamCaption}\item[{const struct \textbf{ osmo\+\_\+fsm} $\ast$}]{fsm,  }\item[{const char $\ast$}]{name }\end{DoxyParamCaption})}



References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ osmo\+\_\+fsm\+::instances}, \textbf{ list}, \textbf{ llist\+\_\+for\+\_\+each\+\_\+entry}, \textbf{ name}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::name}.

\mbox{\label{group__fsm_ga4cd3ac472cde5e97f156d398863e2081}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_free@{osmo\_fsm\_inst\_free}}
\index{osmo\_fsm\_inst\_free@{osmo\_fsm\_inst\_free}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_free()}
{\footnotesize\ttfamily void osmo\+\_\+fsm\+\_\+inst\+\_\+free (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi }\end{DoxyParamCaption})}



delete a given instance of a FSM 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance to be un-\/registered and deleted \\
\hline
\end{DoxyParams}


References \textbf{ fsm\+\_\+free\+\_\+or\+\_\+steal()}, \textbf{ fsm\+\_\+term\+\_\+safely}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::list}, \textbf{ llist\+\_\+del()}, \textbf{ LOGPFSM}, \textbf{ osmo\+\_\+fsm\+\_\+defer\+\_\+free()}, \textbf{ osmo\+\_\+timer\+\_\+del()}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::timer}.



Referenced by \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term()}.

\mbox{\label{group__fsm_ga1279f48c166034158dd79d0bb25664b7}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_name@{osmo\_fsm\_inst\_name}}
\index{osmo\_fsm\_inst\_name@{osmo\_fsm\_inst\_name}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_name()}
{\footnotesize\ttfamily const char $\ast$ osmo\+\_\+fsm\+\_\+inst\+\_\+name (\begin{DoxyParamCaption}\item[{const struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi }\end{DoxyParamCaption})}



get human-\/readable name of FSM instance 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
string rendering of the FSM identity 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ osmo\+\_\+fsm\+::name}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::name}.



Referenced by \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term()}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc\+\_\+child()}.

\mbox{\label{group__fsm_gaf1e0858354f77cffb1386a350b694fe4}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_state\_name@{osmo\_fsm\_inst\_state\_name}}
\index{osmo\_fsm\_inst\_state\_name@{osmo\_fsm\_inst\_state\_name}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_state\_name()}
{\footnotesize\ttfamily static const char $\ast$ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+name (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}



return the name of the state the FSM instance is currently in. 



References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ osmo\+\_\+fsm\+\_\+state\+\_\+name()}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::state}.

\mbox{\label{group__fsm_ga7f88d5cf42077f32bc5cf667ca310d9d}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_unlink\_parent@{osmo\_fsm\_inst\_unlink\_parent}}
\index{osmo\_fsm\_inst\_unlink\_parent@{osmo\_fsm\_inst\_unlink\_parent}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_unlink\_parent()}
{\footnotesize\ttfamily void osmo\+\_\+fsm\+\_\+inst\+\_\+unlink\+\_\+parent (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{void $\ast$}]{ctx }\end{DoxyParamCaption})}



unlink child FSM from its parent FSM. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & Descriptor of the child FSM to unlink. \\
\hline
\mbox{\texttt{ in}}  & {\em ctx} & New talloc context\\
\hline
\end{DoxyParams}
Never call this function from the cleanup callback, because at that time the child FSMs will already be terminated. If unlinking should be performed on FSM termination, use the grace callback instead. 

References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::child}, \textbf{ llist\+\_\+del()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::parent}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::parent\+\_\+term\+\_\+event}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::proc}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+change\+\_\+parent()}.

\mbox{\label{group__fsm_gad28f180033fb18442307fed1d27c3c48}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_update\_id@{osmo\_fsm\_inst\_update\_id}}
\index{osmo\_fsm\_inst\_update\_id@{osmo\_fsm\_inst\_update\_id}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_update\_id()}
{\footnotesize\ttfamily int osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{const char $\ast$}]{id }\end{DoxyParamCaption})}



Change id of the FSM instance. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance \\
\hline
\mbox{\texttt{ in}}  & {\em id} & new ID \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 if the ID was updated, otherwise -\/EINVAL 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id\+\_\+f()}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc()}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id\+\_\+f\+\_\+sanitize()}.

\mbox{\label{group__fsm_ga4373cf363f849faed4fc9885c55a1d22}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_update\_id\_f@{osmo\_fsm\_inst\_update\_id\_f}}
\index{osmo\_fsm\_inst\_update\_id\_f@{osmo\_fsm\_inst\_update\_id\_f}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_update\_id\_f()}
{\footnotesize\ttfamily int osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id\+\_\+f (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{const char $\ast$}]{fmt,  }\item[{}]{... }\end{DoxyParamCaption})}



Change id of the FSM instance using a string format. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance. \\
\hline
\mbox{\texttt{ in}}  & {\em fmt} & format string to compose new ID. \\
\hline
\mbox{\texttt{ in}}  & {\em ...} & variable argument list for format string. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 if the ID was updated, otherwise -\/EINVAL. 
\end{DoxyReturn}


References \textbf{ DLGLOBAL}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::id}, \textbf{ LOGL\+\_\+\+ERROR}, \textbf{ LOGP}, \textbf{ osmo\+\_\+fsm\+::name}, \textbf{ osmo\+\_\+identifier\+\_\+valid()}, \textbf{ osmo\+\_\+quote\+\_\+str()}, and \textbf{ update\+\_\+name()}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id()}.

\mbox{\label{group__fsm_ga0b17e0f3c1b06fff03a0277237145d28}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_inst\_update\_id\_f\_sanitize@{osmo\_fsm\_inst\_update\_id\_f\_sanitize}}
\index{osmo\_fsm\_inst\_update\_id\_f\_sanitize@{osmo\_fsm\_inst\_update\_id\_f\_sanitize}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_inst\_update\_id\_f\_sanitize()}
{\footnotesize\ttfamily int osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id\+\_\+f\+\_\+sanitize (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{char}]{replace\+\_\+with,  }\item[{const char $\ast$}]{fmt,  }\item[{}]{... }\end{DoxyParamCaption})}



Change id of the FSM instance using a string format, and ensuring a valid id. 

Replace any characters that are not permitted as FSM identifier with replace\+\_\+with. 
\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fi} & FSM instance. \\
\hline
\mbox{\texttt{ in}}  & {\em replace\+\_\+with} & Character to use instead of non-\/permitted FSM id characters. Make sure to choose a legal character, e.\+g. \textquotesingle{}-\/\textquotesingle{}. \\
\hline
\mbox{\texttt{ in}}  & {\em fmt} & format string to compose new ID. \\
\hline
\mbox{\texttt{ in}}  & {\em ...} & variable argument list for format string. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 if the ID was updated, otherwise -\/EINVAL. 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id()}, and \textbf{ osmo\+\_\+identifier\+\_\+sanitize\+\_\+buf()}.

\mbox{\label{group__fsm_ga7dacf1bf0ada0d3dc6d2640d24b4aa59}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_log\_addr@{osmo\_fsm\_log\_addr}}
\index{osmo\_fsm\_log\_addr@{osmo\_fsm\_log\_addr}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_log\_addr()}
{\footnotesize\ttfamily void osmo\+\_\+fsm\+\_\+log\+\_\+addr (\begin{DoxyParamCaption}\item[{bool}]{log\+\_\+addr }\end{DoxyParamCaption})}



specify if FSM instance addresses should be logged or not 

By default, the FSM name includes the pointer address of the \doxyref{osmo\+\_\+fsm\+\_\+inst}{p.}{structosmo__fsm__inst}. This behavior can be disabled (and re-\/enabled) using this function.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em log\+\_\+addr} & Indicate if FSM instance address shall be logged \\
\hline
\end{DoxyParams}


References \textbf{ fsm\+\_\+log\+\_\+addr}.

\mbox{\label{group__fsm_ga9f3dad4e32e230e416a8c93401676d42}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_log\_timeouts@{osmo\_fsm\_log\_timeouts}}
\index{osmo\_fsm\_log\_timeouts@{osmo\_fsm\_log\_timeouts}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_log\_timeouts()}
{\footnotesize\ttfamily void osmo\+\_\+fsm\+\_\+log\+\_\+timeouts (\begin{DoxyParamCaption}\item[{bool}]{log\+\_\+timeouts }\end{DoxyParamCaption})}



Enable or disable logging of timeout values for FSM instance state changes. 

By default, state changes are logged by state name only, omitting the timeout. When passing true, each state change will also log the T number (or Osmocom-\/specific X number) and the chosen timeout in seconds. \doxyref{osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer()}{p.}{group__fsm_ga605785659c0482d32c83748f88904ace} will log remaining timeout in millisecond precision.

The default for this is false to reflect legacy behavior. Since various C tests that verify logging output already existed prior to this option, keeping timeout logging off makes sure that they continue to pass. Particularly, \doxyref{osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer()}{p.}{group__fsm_ga605785659c0482d32c83748f88904ace} may cause non-\/deterministic logging of remaining timeout values.

For any program that does not explicitly require deterministic logging output, i.\+e. anything besides regression tests involving FSM instances, it is recommended to call osmo\+\_\+fsm\+\_\+log\+\_\+timeouts(true).


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em log\+\_\+timeouts} & Pass true to log timeouts on state transitions, false to omit timeouts. \\
\hline
\end{DoxyParams}


References \textbf{ fsm\+\_\+log\+\_\+timeouts}.

\mbox{\label{group__fsm_ga444610bbb35d19b21918e61ec4431fa7}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_register@{osmo\_fsm\_register}}
\index{osmo\_fsm\_register@{osmo\_fsm\_register}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_register()}
{\footnotesize\ttfamily int osmo\+\_\+fsm\+\_\+register (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm} $\ast$}]{fsm }\end{DoxyParamCaption})}



register a FSM with the core 

A FSM descriptor needs to be registered with the core before any instances can be created for it.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fsm} & Descriptor of Finite State Machine to be registered \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 on success; negative on error 
\end{DoxyReturn}


References \textbf{ DLGLOBAL}, \textbf{ osmo\+\_\+fsm\+::event\+\_\+names}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ INIT\+\_\+\+LLIST\+\_\+\+HEAD}, \textbf{ osmo\+\_\+fsm\+::instances}, \textbf{ osmo\+\_\+fsm\+::list}, \textbf{ llist\+\_\+add\+\_\+tail()}, \textbf{ LOGL\+\_\+\+ERROR}, \textbf{ LOGP}, \textbf{ osmo\+\_\+fsm\+::name}, \textbf{ osmo\+\_\+fsm\+\_\+find\+\_\+by\+\_\+name()}, \textbf{ osmo\+\_\+g\+\_\+fsms}, and \textbf{ osmo\+\_\+identifier\+\_\+valid()}.

\mbox{\label{group__fsm_gaf031d280ac7d4fc8ac17e8560e5370a8}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_set\_dealloc\_ctx@{osmo\_fsm\_set\_dealloc\_ctx}}
\index{osmo\_fsm\_set\_dealloc\_ctx@{osmo\_fsm\_set\_dealloc\_ctx}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_set\_dealloc\_ctx()}
{\footnotesize\ttfamily void osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx (\begin{DoxyParamCaption}\item[{void $\ast$}]{ctx }\end{DoxyParamCaption})}



Instead of deallocating FSM instances, move them to the given talloc context. 

It is the caller\textquotesingle{}s responsibility to clear this context to actually free the memory of terminated FSM instances. Make sure to not talloc\+\_\+free(ctx) itself before setting a different \doxyref{osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx()}{p.}{group__fsm_gaf031d280ac7d4fc8ac17e8560e5370a8}. To clear a ctx without the need to call \doxyref{osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx()}{p.}{group__fsm_gaf031d280ac7d4fc8ac17e8560e5370a8} again, rather use talloc\+\_\+free\+\_\+children(ctx).

For example, to defer deallocation to the next \doxyref{osmo\+\_\+select\+\_\+main\+\_\+ctx()}{p.}{group__select_ga5a4cd886cd6be70c0a85ed9114ba6d5b} iteration, set this to OTC\+\_\+\+SELECT.

Deferring deallocation is the simplest solution to avoid most use-\/after-\/free problems from FSM instance deallocation. This is a simpler and more general solution than \doxyref{osmo\+\_\+fsm\+\_\+term\+\_\+safely()}{p.}{group__fsm_ga7ae199b946d722bc789b1c59f7c3aa15}.

To disable the feature again, pass NULL as ctx.

Both \doxyref{osmo\+\_\+fsm\+\_\+term\+\_\+safely()}{p.}{group__fsm_ga7ae199b946d722bc789b1c59f7c3aa15} and \doxyref{osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx()}{p.}{group__fsm_gaf031d280ac7d4fc8ac17e8560e5370a8} can be enabled at the same time, which will result in first collecting deallocated FSM instances in fsm\+\_\+term\+\_\+safely.\+collect\+\_\+ctx, and finally reparenting that to the ctx passed here. However, in practice, it does not really make sense to enable both at the same time.


\begin{DoxyParams}{Parameters}
{\em ctx\mbox{[}in\mbox{]}} & Instead of talloc\+\_\+free()int, talloc\+\_\+steal() all future deallocated \doxyref{osmo\+\_\+fsm\+\_\+inst}{p.}{structosmo__fsm__inst} instances to this ctx. If NULL, go back to talloc\+\_\+free() as usual. \\
\hline
\end{DoxyParams}


References \textbf{ fsm\+\_\+term\+\_\+safely}.

\mbox{\label{group__fsm_gae7114ae434235be6e42db8b8231054a8}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_state\_name@{osmo\_fsm\_state\_name}}
\index{osmo\_fsm\_state\_name@{osmo\_fsm\_state\_name}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_state\_name()}
{\footnotesize\ttfamily const char $\ast$ osmo\+\_\+fsm\+\_\+state\+\_\+name (\begin{DoxyParamCaption}\item[{const struct \textbf{ osmo\+\_\+fsm} $\ast$}]{fsm,  }\item[{uint32\+\_\+t}]{state }\end{DoxyParamCaption})}



get human-\/readable name of FSM state 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fsm} & FSM descriptor \\
\hline
\mbox{\texttt{ in}}  & {\em state} & FSM state number \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
string rendering of the FSM state 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ osmo\+\_\+fsm\+\_\+state\+::name}, \textbf{ osmo\+\_\+fsm\+::num\+\_\+states}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::state}, and \textbf{ osmo\+\_\+fsm\+::states}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+name()}, and \textbf{ state\+\_\+chg()}.

\mbox{\label{group__fsm_ga9919c29d9ad5283c475f51c008b52723}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_term\_cause\_name@{osmo\_fsm\_term\_cause\_name}}
\index{osmo\_fsm\_term\_cause\_name@{osmo\_fsm\_term\_cause\_name}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_term\_cause\_name()}
{\footnotesize\ttfamily static const char $\ast$ osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+name (\begin{DoxyParamCaption}\item[{enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause}}]{cause }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}



References \textbf{ cause}, \textbf{ get\+\_\+value\+\_\+string()}, and \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+names}.



Referenced by \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term()}.

\mbox{\label{group__fsm_ga7ae199b946d722bc789b1c59f7c3aa15}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_term\_safely@{osmo\_fsm\_term\_safely}}
\index{osmo\_fsm\_term\_safely@{osmo\_fsm\_term\_safely}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_term\_safely()}
{\footnotesize\ttfamily void osmo\+\_\+fsm\+\_\+term\+\_\+safely (\begin{DoxyParamCaption}\item[{bool}]{term\+\_\+safely }\end{DoxyParamCaption})}



Enable safer way to deallocate cascades of terminating FSM instances. 

Note, using \doxyref{osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx()}{p.}{group__fsm_gaf031d280ac7d4fc8ac17e8560e5370a8} is a more general solution to this same problem. Particularly, in a program using \doxyref{osmo\+\_\+select\+\_\+main\+\_\+ctx()}{p.}{group__select_ga5a4cd886cd6be70c0a85ed9114ba6d5b}, the simplest solution to avoid most use-\/after-\/free problems from FSM instance deallocation is using osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx(\+OTC\+\_\+\+SELECT).

When enabled, an FSM instance termination detects whether another FSM instance is already terminating, and instead of deallocating immediately, collects all terminating FSM instances in a talloc context, to be bulk deallocated once all event handling and termination cascades are done.

For example, if an FSM\textquotesingle{}s cleanup() sends an event to some \char`\"{}other\char`\"{} FSM, which in turn causes the FSM\textquotesingle{}s parent to deallocate, then the parent would talloc\+\_\+free() the child\textquotesingle{}s memory, causing a use-\/after-\/free. There are infinite constellations like this, which all are trivially solved with this feature enabled.

For illustration, see fsm\+\_\+dealloc\+\_\+test.\+c.

When enabled, this feature changes the order of logging, which may break legacy unit test expectations, and changes the order of deallocation to after the parent term event is dispatched.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em term\+\_\+safely} & Pass true to switch to safer FSM instance termination behavior. \\
\hline
\end{DoxyParams}


References \textbf{ fsm\+\_\+term\+\_\+safely\+\_\+enabled}.

\mbox{\label{group__fsm_ga42d9cd0b40e6ffc26c8285861776d8e0}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_unregister@{osmo\_fsm\_unregister}}
\index{osmo\_fsm\_unregister@{osmo\_fsm\_unregister}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_unregister()}
{\footnotesize\ttfamily void osmo\+\_\+fsm\+\_\+unregister (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm} $\ast$}]{fsm }\end{DoxyParamCaption})}



unregister a FSM from the core 

Once the FSM descriptor is unregistered, active instances can still use it, but no new instances may be created for it.


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em fsm} & Descriptor of Finite State Machine to be removed \\
\hline
\end{DoxyParams}


References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ osmo\+\_\+fsm\+::list}, and \textbf{ llist\+\_\+del()}.

\mbox{\label{group__fsm_ga96fb76c74cd793b6513b33f4041540a3}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!state\_chg@{state\_chg}}
\index{state\_chg@{state\_chg}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{state\_chg()}
{\footnotesize\ttfamily static int state\+\_\+chg (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi,  }\item[{uint32\+\_\+t}]{new\+\_\+state,  }\item[{bool}]{keep\+\_\+timer,  }\item[{unsigned long}]{timeout\+\_\+ms,  }\item[{int}]{T,  }\item[{const char $\ast$}]{file,  }\item[{int}]{line }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [static]}}



References \textbf{ osmo\+\_\+timer\+\_\+list\+::active}, \textbf{ file()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ fsm\+\_\+log\+\_\+timeouts}, \textbf{ LOGL\+\_\+\+ERROR}, \textbf{ LOGPFSMLSRC}, \textbf{ LOGPFSMSRC}, \textbf{ osmo\+\_\+fsm\+\_\+state\+::onenter}, \textbf{ osmo\+\_\+fsm\+\_\+state\+::onleave}, \textbf{ osmo\+\_\+fsm\+\_\+state\+\_\+name()}, \textbf{ OSMO\+\_\+\+T\+\_\+\+FMT}, \textbf{ OSMO\+\_\+\+T\+\_\+\+FMT\+\_\+\+ARGS}, \textbf{ osmo\+\_\+timer\+\_\+del()}, \textbf{ osmo\+\_\+timer\+\_\+pending()}, \textbf{ osmo\+\_\+timer\+\_\+remaining()}, \textbf{ osmo\+\_\+timer\+\_\+schedule()}, \textbf{ osmo\+\_\+fsm\+\_\+state\+::out\+\_\+state\+\_\+mask}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::proc}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::state}, \textbf{ osmo\+\_\+fsm\+::states}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::T}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::terminating}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::timer}.



Referenced by \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg()}, \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer()}, \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer\+\_\+ms()}, \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer()}, and \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+ms()}.

\mbox{\label{group__fsm_ga1380b8cda91ee170848d1e9646135b93}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!update\_name@{update\_name}}
\index{update\_name@{update\_name}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{update\_name()}
{\footnotesize\ttfamily static void update\+\_\+name (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$}]{fi }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [static]}}



References \textbf{ osmo\+\_\+fsm\+\_\+inst\+::fsm}, \textbf{ fsm\+\_\+log\+\_\+addr}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+::id}, \textbf{ osmo\+\_\+fsm\+::name}, and \textbf{ osmo\+\_\+fsm\+\_\+inst\+::name}.



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id\+\_\+f()}.



\doxysubsection{Variable Documentation}
\mbox{\label{group__fsm_gae90f394c74af496ec8e2d9f28d5a33e3}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!collect\_ctx@{collect\_ctx}}
\index{collect\_ctx@{collect\_ctx}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{}
{\footnotesize\ttfamily void$\ast$  \{ ... \} \+::collect\+\_\+ctx}



Talloc context to collect all deferred deallocations (FSM instances, and talloc objects if any). 

\mbox{\label{group__fsm_gadb38c1eacffc5676250b9856f78adc9a}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!depth@{depth}}
\index{depth@{depth}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{}
{\footnotesize\ttfamily unsigned int  \{ ... \} \+::depth}



2 if a secondary FSM terminates, 3 if a secondary FSM causes a tertiary FSM to terminate, and so on. 

\mbox{\label{group__fsm_gadd96e3ac8aff35000ec480ca104709f8}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!fsm\_dealloc\_ctx@{fsm\_dealloc\_ctx}}
\index{fsm\_dealloc\_ctx@{fsm\_dealloc\_ctx}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{}
{\footnotesize\ttfamily void$\ast$  \{ ... \} \+::fsm\+\_\+dealloc\+\_\+ctx}



See \doxyref{osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx()}{p.}{group__fsm_gaf031d280ac7d4fc8ac17e8560e5370a8} 

\mbox{\label{group__fsm_ga90bb7135bd876e3de07ecb1c8d74047b}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!fsm\_log\_addr@{fsm\_log\_addr}}
\index{fsm\_log\_addr@{fsm\_log\_addr}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{fsm\_log\_addr}
{\footnotesize\ttfamily bool fsm\+\_\+log\+\_\+addr = true\hspace{0.3cm}{\ttfamily [static]}}



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+log\+\_\+addr()}, and \textbf{ update\+\_\+name()}.

\mbox{\label{group__fsm_gab4ec2d8fbd00ee01c1483e8693f1d476}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!fsm\_log\_timeouts@{fsm\_log\_timeouts}}
\index{fsm\_log\_timeouts@{fsm\_log\_timeouts}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{fsm\_log\_timeouts}
{\footnotesize\ttfamily bool fsm\+\_\+log\+\_\+timeouts = false\hspace{0.3cm}{\ttfamily [static]}}



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+log\+\_\+timeouts()}, and \textbf{ state\+\_\+chg()}.

\mbox{\label{group__fsm_ga27502d517e5030ea4d091947186e55ac}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!fsm\_term\_safely@{fsm\_term\_safely}}
\index{fsm\_term\_safely@{fsm\_term\_safely}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{}
{\footnotesize\ttfamily \+\_\+\+\_\+thread struct  \{ ... \}  fsm\+\_\+term\+\_\+safely\hspace{0.3cm}{\ttfamily [static]}}



Internal state for FSM instance termination cascades. 



Referenced by \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term()}, \textbf{ fsm\+\_\+free\+\_\+or\+\_\+steal()}, \textbf{ osmo\+\_\+fsm\+\_\+defer\+\_\+free()}, \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+free()}, and \textbf{ osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx()}.

\mbox{\label{group__fsm_ga821e471c0c64e832f6f5d8ab621676ee}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!fsm\_term\_safely\_enabled@{fsm\_term\_safely\_enabled}}
\index{fsm\_term\_safely\_enabled@{fsm\_term\_safely\_enabled}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{fsm\_term\_safely\_enabled}
{\footnotesize\ttfamily bool fsm\+\_\+term\+\_\+safely\+\_\+enabled = false\hspace{0.3cm}{\ttfamily [static]}}



See \doxyref{osmo\+\_\+fsm\+\_\+term\+\_\+safely()}{p.}{group__fsm_ga7ae199b946d722bc789b1c59f7c3aa15}. 



Referenced by \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term()}, and \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+safely()}.

\mbox{\label{group__fsm_ga4c11df3f81765eb1ee987d95d3f0d07e}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_term\_cause\_names@{osmo\_fsm\_term\_cause\_names}}
\index{osmo\_fsm\_term\_cause\_names@{osmo\_fsm\_term\_cause\_names}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_term\_cause\_names\hspace{0.1cm}{\footnotesize\ttfamily [1/2]}}
{\footnotesize\ttfamily const struct \textbf{ value\+\_\+string} osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+names[$\,$]\hspace{0.3cm}{\ttfamily [extern]}}



Referenced by \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+name()}.

\mbox{\label{group__fsm_ga4c11df3f81765eb1ee987d95d3f0d07e}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!osmo\_fsm\_term\_cause\_names@{osmo\_fsm\_term\_cause\_names}}
\index{osmo\_fsm\_term\_cause\_names@{osmo\_fsm\_term\_cause\_names}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{osmo\_fsm\_term\_cause\_names\hspace{0.1cm}{\footnotesize\ttfamily [2/2]}}
{\footnotesize\ttfamily const struct \textbf{ value\+\_\+string} osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+names[$\,$]}

{\bfseries Initial value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{= \{}
\DoxyCodeLine{        OSMO\_VALUE\_STRING(OSMO\_FSM\_TERM\_PARENT),}
\DoxyCodeLine{        OSMO\_VALUE\_STRING(OSMO\_FSM\_TERM\_REQUEST),}
\DoxyCodeLine{        OSMO\_VALUE\_STRING(OSMO\_FSM\_TERM\_REGULAR),}
\DoxyCodeLine{        OSMO\_VALUE\_STRING(OSMO\_FSM\_TERM\_ERROR),}
\DoxyCodeLine{        OSMO\_VALUE\_STRING(OSMO\_FSM\_TERM\_TIMEOUT),}
\DoxyCodeLine{        \{ 0, NULL \}}
\DoxyCodeLine{\}}

\end{DoxyCode}


Referenced by \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+name()}.

\mbox{\label{group__fsm_ga59706d0226f5c1a07c433ba87c8c6c34}} 
\index{Finite State Machine abstraction@{Finite State Machine abstraction}!root\_fi@{root\_fi}}
\index{root\_fi@{root\_fi}!Finite State Machine abstraction@{Finite State Machine abstraction}}
\doxysubsubsection{}
{\footnotesize\ttfamily struct osmo\+\_\+fsm\+\_\+inst$\ast$  \{ ... \} \+::root\+\_\+fi}



The first FSM instance that invoked \doxyref{osmo\+\_\+fsm\+\_\+inst\+\_\+term()}{p.}{group__fsm_ga22397fdc69a4f1c303bb0b2694d5f2aa} in the current cascade. 

