[Libunwind-devel] [PATCH 2/2] doc: write about _UPT_get_proc_name and _UPT_flush_map_cache

[Masatake YAMATO]

Signed-off-by: Masatake YAMATO <address@hidden>
---
 doc/libunwind-ptrace.tex | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/libunwind-ptrace.tex b/doc/libunwind-ptrace.tex
index fe074d8..a2fe8a9 100644
--- a/doc/libunwind-ptrace.tex
+++ b/doc/libunwind-ptrace.tex
@@ -15,6 +15,7 @@
 \noindent
 \Type{unw\_accessors\_t} \Var{\_UPT\_accessors};\\
 
+\noindent
 \Type{void~*}\Func{\_UPT\_create}(\Type{pid\_t});\\
 \noindent
 \Type{void} \Func{\_UPT\_destroy}(\Type{void~*});\\
@@ -36,6 +37,11 @@
 \noindent
 \Type{int} \Func{\_UPT\_resume}(\Type{unw\_addr\_space\_t}, 
\Type{unw\_cursor\_t~*}, \Type{void~*});\\
 
+\noindent
+\Type{void} \Func{\_UPT\_set\_map\_caching\_policy}(\Type{void~*}, 
\Type{upt\_map\_caching\_policy\_t});\\
+\noindent
+\Type{void} \Func{\_UPT\_flush\_map\_cache}(\Type{void~*});\\
+
 \section{Description}
 
 The \Func{ptrace}(2) system-call makes it possible for a process to
@@ -86,6 +92,23 @@ void-pointer that was returned by the corresponding call to
 \Func{\_UPT\_create}().  This ensures that all memory and other
 resources are freed up.
 
+\section{Map Cache}
+On linux this library reads \File{/proc/pid/maps} to get the
+memory mapping of the target process. By default the \File{maps} is
+read each time when \Func{\_UPT\_get\_proc\_name} is invoked because
+the memory mapping can be altered anytime with system call like
+\Func{mmap}.  However, if an application using this library can be
+know the timing when the memory mapping is altered, some of rereading
+of \File{maps} can be avoided.
+
+A cache mechanism for the \File{maps} can be enabled by calling
+\Func{\_UPT\_set\_map\_caching\_policy} with
+\Const{UNW\_MAP\_CACHE\_ENABLE}; and can be disabled with
+\Const{UNW\_MAP\_CACHE\_NONE}. The application enabling the mechanism
+must track the alteration of the memory mapping and notify it with
+\Func{\_UPT\_flush\_map\_cache} to the library. The function triggers
+the rereading the file.
+
 \section{Availability}
 
 Since \Func{ptrace}(2) works within a single machine only, the
-- 
1.8.3.1