\hypertarget{topology_8h}{
\section{include/topology.h File Reference}
\label{topology_8h}\index{include/topology.h@{include/topology.h}}
}


libtopology -\/ a library for discovering Linux system topology  


\subsection*{Defines}
\begin{DoxyCompactItemize}
\item 
\#define \hyperlink{topology_8h_ae6895ae6d85c34bb346fdd222c9a8c03}{topology\_\-for\_\-each\_\-device\_\-of\_\-type}(ctx, dev, type)
\end{DoxyCompactItemize}
\subsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
\hypertarget{topology_8h_a7d38d65c561895a8c51348ab467ac26a}{
typedef unsigned long {\bfseries topo\_\-context\_\-t}}
\label{topology_8h_a7d38d65c561895a8c51348ab467ac26a}

\item 
\hypertarget{topology_8h_abebc8f02307f19c723e3a6f2c7017bae}{
typedef unsigned long {\bfseries topo\_\-procent\_\-t}}
\label{topology_8h_abebc8f02307f19c723e3a6f2c7017bae}

\item 
\hypertarget{topology_8h_a6e89d8d16ecc43d6314b57a508358079}{
typedef unsigned long {\bfseries topo\_\-device\_\-t}}
\label{topology_8h_a6e89d8d16ecc43d6314b57a508358079}

\item 
\hypertarget{topology_8h_a49a507b715610d695fd0cb91b97d70f2}{
typedef enum topology\_\-level {\bfseries topo\_\-level\_\-t}}
\label{topology_8h_a49a507b715610d695fd0cb91b97d70f2}

\end{DoxyCompactItemize}
\subsection*{Enumerations}
\begin{DoxyCompactItemize}
\item 
enum {\bfseries topology\_\-level} \{ \par
{\bfseries TOPOLOGY\_\-THREAD} =  1, 
{\bfseries TOPOLOGY\_\-CORE}, 
{\bfseries TOPOLOGY\_\-PACKAGE}, 
{\bfseries TOPOLOGY\_\-NODE}, 
\par
{\bfseries TOPOLOGY\_\-SYSTEM}
 \}
\end{DoxyCompactItemize}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
int \hyperlink{topology_8h_a31820c2cd443c201e3c0b49bbf95f5e8}{topology\_\-init\_\-context} (topo\_\-context\_\-t $\ast$ctx, topo\_\-procent\_\-t $\ast$system)
\item 
void \hyperlink{topology_8h_a8b138258fae846a297f4ebd8e9ed18be}{topology\_\-free\_\-context} (topo\_\-context\_\-t ctx)
\item 
size\_\-t \hyperlink{topology_8h_ae7dfacf839321a6514334a3265504ffa}{topology\_\-sizeof\_\-cpumask} (topo\_\-context\_\-t ctx)
\item 
topo\_\-procent\_\-t \hyperlink{topology_8h_a447457295957e58b67ecf8b0f174091b}{topology\_\-traverse} (topo\_\-procent\_\-t start, topo\_\-procent\_\-t iter, topo\_\-level\_\-t to\_\-level)
\item 
void \hyperlink{topology_8h_aad9b02723a0afcd23d20c7b150064eda}{topology\_\-procent\_\-cpumask} (topo\_\-procent\_\-t ent, cpu\_\-set\_\-t $\ast$dest)
\item 
topo\_\-device\_\-t \hyperlink{topology_8h_abb206137614a1770cd2301561b594444}{topology\_\-find\_\-device\_\-by\_\-type} (topo\_\-context\_\-t ctx, topo\_\-device\_\-t prev, const char $\ast$type)
\item 
void \hyperlink{topology_8h_a777a9a669c27efa683a309e4d9149a64}{topology\_\-device\_\-cpumask} (topo\_\-device\_\-t dev, cpu\_\-set\_\-t $\ast$dest)
\item 
const char $\ast$ \hyperlink{topology_8h_ac70442a64bdcec2a6bf70025fc06f7c0}{topology\_\-device\_\-get\_\-attribute} (topo\_\-device\_\-t dev, const char $\ast$name)
\end{DoxyCompactItemize}


\subsection{Detailed Description}
libtopology -\/ a library for discovering Linux system topology The libtopology API allows one to formulate scheduling and NUMA policies in terms that are abstract and portable. 

\subsection{Define Documentation}
\hypertarget{topology_8h_ae6895ae6d85c34bb346fdd222c9a8c03}{
\index{topology.h@{topology.h}!topology\_\-for\_\-each\_\-device\_\-of\_\-type@{topology\_\-for\_\-each\_\-device\_\-of\_\-type}}
\index{topology\_\-for\_\-each\_\-device\_\-of\_\-type@{topology\_\-for\_\-each\_\-device\_\-of\_\-type}!topology.h@{topology.h}}
\subsubsection[{topology\_\-for\_\-each\_\-device\_\-of\_\-type}]{\setlength{\rightskip}{0pt plus 5cm}\#define topology\_\-for\_\-each\_\-device\_\-of\_\-type(
\begin{DoxyParamCaption}
\item[{}]{ctx, }
\item[{}]{dev, }
\item[{}]{type}
\end{DoxyParamCaption}
)}}
\label{topology_8h_ae6895ae6d85c34bb346fdd222c9a8c03}
{\bfseries Value:}
\begin{DoxyCode}
for ((dev) = topology_find_device_by_type((ctx), (topo_device_t)0, (type)); \
             (dev) != 0;                                                         
         \
             (dev) = topology_find_device_by_type((ctx), (dev), (type)))
\end{DoxyCode}
\hyperlink{topology_8h_ae6895ae6d85c34bb346fdd222c9a8c03}{topology\_\-for\_\-each\_\-device\_\-of\_\-type()} -\/ Iterate over all devices matching type


\begin{DoxyParams}{Parameters}
{\em ctx} & -\/ Topology context in use \\
\hline
{\em dev} & -\/ struct topo\_\-device $\ast$ iterator \\
\hline
{\em type} & -\/ type string, e.g. \char`\"{}cache\char`\"{}\\
\hline
\end{DoxyParams}
The order in which devices are returned is unspecified. 

\subsection{Function Documentation}
\hypertarget{topology_8h_a31820c2cd443c201e3c0b49bbf95f5e8}{
\index{topology.h@{topology.h}!topology\_\-init\_\-context@{topology\_\-init\_\-context}}
\index{topology\_\-init\_\-context@{topology\_\-init\_\-context}!topology.h@{topology.h}}
\subsubsection[{topology\_\-init\_\-context}]{\setlength{\rightskip}{0pt plus 5cm}int topology\_\-init\_\-context (
\begin{DoxyParamCaption}
\item[{topo\_\-context\_\-t $\ast$}]{ctx, }
\item[{topo\_\-procent\_\-t $\ast$}]{system}
\end{DoxyParamCaption}
)}}
\label{topology_8h_a31820c2cd443c201e3c0b49bbf95f5e8}
\hyperlink{topology_8h_a31820c2cd443c201e3c0b49bbf95f5e8}{topology\_\-init\_\-context()} -\/ Allocate a topology context


\begin{DoxyParams}{Parameters}
{\em ctx} & -\/ address of topo\_\-context\_\-t \\
\hline
{\em system} & -\/ address of system topo\_\-procent\_\-t\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 on success, non-\/zero on failure.
\end{DoxyReturn}
On success ctx will contain a valid handle for a topology context which can be used with other topology APIs. If the system pointer is non-\/NULL, on success it contains a handle corresponding to the top-\/level system object, from which all other topo\_\-procent\_\-t objects in the system (nodes, packages, cores, and threads) can be reached.

On failure the contents of ctx and system are unspecified. \hypertarget{topology_8h_a8b138258fae846a297f4ebd8e9ed18be}{
\index{topology.h@{topology.h}!topology\_\-free\_\-context@{topology\_\-free\_\-context}}
\index{topology\_\-free\_\-context@{topology\_\-free\_\-context}!topology.h@{topology.h}}
\subsubsection[{topology\_\-free\_\-context}]{\setlength{\rightskip}{0pt plus 5cm}void topology\_\-free\_\-context (
\begin{DoxyParamCaption}
\item[{topo\_\-context\_\-t}]{ctx}
\end{DoxyParamCaption}
)}}
\label{topology_8h_a8b138258fae846a297f4ebd8e9ed18be}
\hyperlink{topology_8h_a8b138258fae846a297f4ebd8e9ed18be}{topology\_\-free\_\-context()} -\/ Release a topology context


\begin{DoxyParams}{Parameters}
{\em ctx} & -\/ context to release\\
\hline
\end{DoxyParams}
Releases the resources associated with a valid topology context provided by \hyperlink{topology_8h_a31820c2cd443c201e3c0b49bbf95f5e8}{topology\_\-init\_\-context()}. After a call to \hyperlink{topology_8h_a8b138258fae846a297f4ebd8e9ed18be}{topology\_\-free\_\-context()}, ctx is considered invalid and must not be passed to other topology APIs. This function should be called only after all other operations on this context or its derived objects have completed. In other words, \hyperlink{topology_8h_a8b138258fae846a297f4ebd8e9ed18be}{topology\_\-free\_\-context()} should not be called until the user is done making libtopology calls. \hypertarget{topology_8h_ae7dfacf839321a6514334a3265504ffa}{
\index{topology.h@{topology.h}!topology\_\-sizeof\_\-cpumask@{topology\_\-sizeof\_\-cpumask}}
\index{topology\_\-sizeof\_\-cpumask@{topology\_\-sizeof\_\-cpumask}!topology.h@{topology.h}}
\subsubsection[{topology\_\-sizeof\_\-cpumask}]{\setlength{\rightskip}{0pt plus 5cm}size\_\-t topology\_\-sizeof\_\-cpumask (
\begin{DoxyParamCaption}
\item[{topo\_\-context\_\-t}]{ctx}
\end{DoxyParamCaption}
)}}
\label{topology_8h_ae7dfacf839321a6514334a3265504ffa}
\hyperlink{topology_8h_ae7dfacf839321a6514334a3265504ffa}{topology\_\-sizeof\_\-cpumask()} -\/ get the size of cpumasks used by libtopology


\begin{DoxyParams}{Parameters}
{\em ctx} & -\/ a valid context returned from \hyperlink{topology_8h_a31820c2cd443c201e3c0b49bbf95f5e8}{topology\_\-init\_\-context()}\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
The size in bytes of cpumask objects used by libtopology for this context.
\end{DoxyReturn}
During context initialization, libtopology may dynamically determine the size of the cpumask data structure (a bitfield representing a set of logical CPU ids), which is used to indicate the set of logical CPUs with which an object is associated. The value returned by this function is the size which must be used to allocate cpu\_\-set\_\-t objects which are passed to the libtopology API (e.g. \hyperlink{topology_8h_a777a9a669c27efa683a309e4d9149a64}{topology\_\-device\_\-cpumask()}).

\begin{DoxySeeAlso}{See also}
\hyperlink{topology_8h_a777a9a669c27efa683a309e4d9149a64}{topology\_\-device\_\-cpumask} 

\hyperlink{topology_8h_aad9b02723a0afcd23d20c7b150064eda}{topology\_\-procent\_\-cpumask} 
\end{DoxySeeAlso}
\hypertarget{topology_8h_a447457295957e58b67ecf8b0f174091b}{
\index{topology.h@{topology.h}!topology\_\-traverse@{topology\_\-traverse}}
\index{topology\_\-traverse@{topology\_\-traverse}!topology.h@{topology.h}}
\subsubsection[{topology\_\-traverse}]{\setlength{\rightskip}{0pt plus 5cm}topo\_\-procent\_\-t topology\_\-traverse (
\begin{DoxyParamCaption}
\item[{topo\_\-procent\_\-t}]{start, }
\item[{topo\_\-procent\_\-t}]{iter, }
\item[{topo\_\-level\_\-t}]{to\_\-level}
\end{DoxyParamCaption}
)}}
\label{topology_8h_a447457295957e58b67ecf8b0f174091b}
\hyperlink{topology_8h_a447457295957e58b67ecf8b0f174091b}{topology\_\-traverse()} -\/ traverse from one processor entity to others


\begin{DoxyParams}{Parameters}
{\em start} & -\/ starting point in procent hierarchy \\
\hline
{\em iter} & -\/ value returned from previous call to \hyperlink{topology_8h_a447457295957e58b67ecf8b0f174091b}{topology\_\-traverse()}, or 0 \\
\hline
{\em to\_\-level} & -\/ the topology\_\-level value which returned objects must match\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
The next topo\_\-procent\_\-t object at the level specified, relative to start and iter.
\end{DoxyReturn}
This function can be used to interrogate the topo\_\-procent\_\-t hierarchy. The iter argument is consulted when traversing an object's constituents or \char`\"{}children\char`\"{}, i.e. when to\_\-level is less than the starting point's level. \hypertarget{topology_8h_aad9b02723a0afcd23d20c7b150064eda}{
\index{topology.h@{topology.h}!topology\_\-procent\_\-cpumask@{topology\_\-procent\_\-cpumask}}
\index{topology\_\-procent\_\-cpumask@{topology\_\-procent\_\-cpumask}!topology.h@{topology.h}}
\subsubsection[{topology\_\-procent\_\-cpumask}]{\setlength{\rightskip}{0pt plus 5cm}void topology\_\-procent\_\-cpumask (
\begin{DoxyParamCaption}
\item[{topo\_\-procent\_\-t}]{ent, }
\item[{cpu\_\-set\_\-t $\ast$}]{dest}
\end{DoxyParamCaption}
)}}
\label{topology_8h_aad9b02723a0afcd23d20c7b150064eda}
\hyperlink{topology_8h_aad9b02723a0afcd23d20c7b150064eda}{topology\_\-procent\_\-cpumask()} -\/ copy a topo\_\-procent\_\-t's cpumask


\begin{DoxyParams}{Parameters}
{\em ent} & -\/ topo\_\-procent\_\-t to query \\
\hline
{\em dest} & -\/ pointer to cpu\_\-set\_\-t allocated by the caller\\
\hline
\end{DoxyParams}
Copies ent's cpumask to the cpumask buffer provided by the caller. The size of the cpumask buffer must be equal to the size returned by \hyperlink{topology_8h_ae7dfacf839321a6514334a3265504ffa}{topology\_\-sizeof\_\-cpumask()}.

\begin{DoxySeeAlso}{See also}
\hyperlink{topology_8h_ae7dfacf839321a6514334a3265504ffa}{topology\_\-sizeof\_\-cpumask} 
\end{DoxySeeAlso}
\hypertarget{topology_8h_abb206137614a1770cd2301561b594444}{
\index{topology.h@{topology.h}!topology\_\-find\_\-device\_\-by\_\-type@{topology\_\-find\_\-device\_\-by\_\-type}}
\index{topology\_\-find\_\-device\_\-by\_\-type@{topology\_\-find\_\-device\_\-by\_\-type}!topology.h@{topology.h}}
\subsubsection[{topology\_\-find\_\-device\_\-by\_\-type}]{\setlength{\rightskip}{0pt plus 5cm}topo\_\-device\_\-t topology\_\-find\_\-device\_\-by\_\-type (
\begin{DoxyParamCaption}
\item[{topo\_\-context\_\-t}]{ctx, }
\item[{topo\_\-device\_\-t}]{prev, }
\item[{const char $\ast$}]{type}
\end{DoxyParamCaption}
)}}
\label{topology_8h_abb206137614a1770cd2301561b594444}
\hyperlink{topology_8h_abb206137614a1770cd2301561b594444}{topology\_\-find\_\-device\_\-by\_\-type()} -\/ Iterate from one device to the next of the given type 
\begin{DoxyParams}{Parameters}
{\em ctx} & -\/ Topology context in use \\
\hline
{\em prev} & -\/ 0, or a topo\_\-device\_\-t returned by a previous call to \hyperlink{topology_8h_abb206137614a1770cd2301561b594444}{topology\_\-find\_\-device\_\-by\_\-type()} \\
\hline
{\em type} & -\/ type string, e.g. \char`\"{}cache\char`\"{} \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
The next device matching the given type
\end{DoxyReturn}
This interface is useful primarily in combination with \hyperlink{topology_8h_ae6895ae6d85c34bb346fdd222c9a8c03}{topology\_\-for\_\-each\_\-device\_\-of\_\-type()} to iterate over a the devices matching the given type. The order in which devices are returned is unspecified.

\begin{DoxySeeAlso}{See also}
\hyperlink{topology_8h_ae6895ae6d85c34bb346fdd222c9a8c03}{topology\_\-for\_\-each\_\-device\_\-of\_\-type} 
\end{DoxySeeAlso}
\hypertarget{topology_8h_a777a9a669c27efa683a309e4d9149a64}{
\index{topology.h@{topology.h}!topology\_\-device\_\-cpumask@{topology\_\-device\_\-cpumask}}
\index{topology\_\-device\_\-cpumask@{topology\_\-device\_\-cpumask}!topology.h@{topology.h}}
\subsubsection[{topology\_\-device\_\-cpumask}]{\setlength{\rightskip}{0pt plus 5cm}void topology\_\-device\_\-cpumask (
\begin{DoxyParamCaption}
\item[{topo\_\-device\_\-t}]{dev, }
\item[{cpu\_\-set\_\-t $\ast$}]{dest}
\end{DoxyParamCaption}
)}}
\label{topology_8h_a777a9a669c27efa683a309e4d9149a64}
\hyperlink{topology_8h_a777a9a669c27efa683a309e4d9149a64}{topology\_\-device\_\-cpumask()} -\/ copy a topo\_\-device\_\-t's cpumask


\begin{DoxyParams}{Parameters}
{\em dev} & -\/ topo\_\-device\_\-t to query \\
\hline
{\em dest} & -\/ pointer to cpu\_\-set\_\-t allocated by the caller\\
\hline
\end{DoxyParams}
Copies the given device's cpumask to the cpumask buffer provided by the caller. The size of the cpumask buffer must be equal to the size returned by \hyperlink{topology_8h_ae7dfacf839321a6514334a3265504ffa}{topology\_\-sizeof\_\-cpumask()}.

\begin{DoxySeeAlso}{See also}
\hyperlink{topology_8h_ae7dfacf839321a6514334a3265504ffa}{topology\_\-sizeof\_\-cpumask} 
\end{DoxySeeAlso}
\hypertarget{topology_8h_ac70442a64bdcec2a6bf70025fc06f7c0}{
\index{topology.h@{topology.h}!topology\_\-device\_\-get\_\-attribute@{topology\_\-device\_\-get\_\-attribute}}
\index{topology\_\-device\_\-get\_\-attribute@{topology\_\-device\_\-get\_\-attribute}!topology.h@{topology.h}}
\subsubsection[{topology\_\-device\_\-get\_\-attribute}]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ topology\_\-device\_\-get\_\-attribute (
\begin{DoxyParamCaption}
\item[{topo\_\-device\_\-t}]{dev, }
\item[{const char $\ast$}]{name}
\end{DoxyParamCaption}
)}}
\label{topology_8h_ac70442a64bdcec2a6bf70025fc06f7c0}
topology\_\-device\_\-get\_\-attribute -\/ query the properties of a device


\begin{DoxyParams}{Parameters}
{\em dev} & -\/ topo\_\-device $\ast$ \\
\hline
{\em name} & -\/ string identifying the attribute \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
The value of the attribute for the given device.
\end{DoxyReturn}
If the device has no attribute matching the given name, returns NULL. The pointer returned refers to memory allocated by libtopology; if the user intends to use this value after releasing the context associated with dev, a copy should be made.