File: group__qfits__cache.html

package info (click to toggle)
qfits 6.2.0-8
  • links: PTS
  • area: main
  • in suites: bookworm, bullseye, buster, jessie, jessie-kfreebsd, stretch
  • size: 2,976 kB
  • ctags: 1,019
  • sloc: ansic: 11,631; sh: 8,330; makefile: 131
file content (119 lines) | stat: -rw-r--r-- 6,265 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
<html>
<head>
<meta name="keywords"           content="eso, FITS format, C library">
<link href="doxygen.css" rel="stylesheet" type="text/css">
<title>QFITS Reference Manual 6.2.0</title>
</head>

<body text="#000000" bgcolor="#ffffff">



<!-- Generated by Doxygen 1.4.1 -->
<h1>FITS caching capabilities</h1><table border="0" cellpadding="0" cellspacing="0">
<tr><td></td></tr>
<tr><td colspan="2"><br><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__qfits__cache.html#ga0">qfits_cache_purge</a> (void)</td></tr>

<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Purge the qfits cache.  <a href="#ga0"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__qfits__cache.html#ga1">qfits_query</a> (const char *filename, int what)</td></tr>

<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Query a FITS file offset from the cache.  <a href="#ga1"></a><br></td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
This modules implements a cache for FITS access routines. The first time a FITS file is seen by the library, all corresponding pointers are cached here. This speeds up multiple accesses to large files by magnitudes. <hr><h2>Function Documentation</h2>
<a class="anchor" name="ga0" doxytag="qfits_cache.c::qfits_cache_purge"></a><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
  <tr>
    <td class="mdRow">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top">void qfits_cache_purge           </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="md" nowrap valign="top">void&nbsp;</td>
          <td class="mdname1" valign="top" nowrap>          </td>
          <td class="md" valign="top">&nbsp;)&nbsp;</td>
          <td class="md" nowrap></td>
        </tr>
      </table>
    </td>
  </tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
Purge the qfits cache. 
<p>
<dl compact><dt><b>Returns:</b></dt><dd>void</dd></dl>
This function is useful for programs running for a long period, to clean up the cache. Ideally in a daemon, it should be called by a timer at regular intervals. Notice that since the cache is fairly small, you should not need to care too much about this.     </td>
  </tr>
</table>
<a class="anchor" name="ga1" doxytag="qfits_cache.c::qfits_query"></a><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
  <tr>
    <td class="mdRow">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top">int qfits_query           </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="md" nowrap valign="top">const char *&nbsp;</td>
          <td class="mdname" nowrap> <em>filename</em>, </td>
        </tr>
        <tr>
          <td class="md" nowrap align="right"></td>
          <td class="md"></td>
          <td class="md" nowrap>int&nbsp;</td>
          <td class="mdname" nowrap> <em>what</em></td>
        </tr>
        <tr>
          <td class="md"></td>
          <td class="md">)&nbsp;</td>
          <td class="md" colspan="2"></td>
        </tr>
      </table>
    </td>
  </tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
Query a FITS file offset from the cache. 
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>filename</em>&nbsp;</td><td>Name of the file to examine. </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>what</em>&nbsp;</td><td>What should be queried (see below). </td></tr>
  </table>
</dl>
<dl compact><dt><b>Returns:</b></dt><dd>an integer offset, or -1 if an error occurred.</dd></dl>
This function queries the cache for FITS offset information. If the requested file name has never been seen before, it is completely parsed to extract all offset informations, which are then stored in the cache. The next query will get the informations from the cache, avoiding a complete re-parsing of the file. This is especially useful for large FITS files with lots of extensions, because querying the extensions is an expensive operation.<p>
This operation has side-effects: the cache is an automatically allocated structure in memory, that can only grow. Every request on a new FITS file will make it grow. The structure is pretty light-weight in memory, but nonetheless this is an issue for daemon-type programs which must run over long periods. The solution is to clean the cache using <a class="el" href="group__qfits__cache.html#ga0">qfits_cache_purge()</a> at regular intervals. This is left to the user of this library.<p>
To request information about a FITS file, you must pass an integer built from the following symbols:<p>
<ul>
<li><code>QFITS_QUERY_N_EXT</code> </li><li><code>QFITS_QUERY_HDR_START</code> </li><li><code>QFITS_QUERY_DAT_START</code> </li><li><code>QFITS_QUERY_HDR_SIZE</code> </li><li><code>QFITS_QUERY_DAT_SIZE</code> </li></ul>
<p>
Querying the number of extensions present in a file is done simply with:<p>
<div class="fragment"><pre class="fragment">  next = <a class="code" href="group__qfits__cache.html#ga1">qfits_query</a>(filename, QFITS_QUERY_N_EXT);
</pre></div><p>
Querying the offset to the i-th extension header is done with:<p>
<div class="fragment"><pre class="fragment">  off = <a class="code" href="group__qfits__cache.html#ga1">qfits_query</a>(filename, QFITS_QUERY_HDR_START | i);
</pre></div><p>
i.e. you must OR (|) the extension number with the <code>QFITS_QUERY_HDR_START</code> symbol. Requesting offsets to extension data is done in the same way:<p>
<div class="fragment"><pre class="fragment">  off = <a class="code" href="group__qfits__cache.html#ga1">qfits_query</a>(filename, QFITS_QUERY_DAT_START | i);
</pre></div><p>
Notice that extension 0 is the main header and main data part of the FITS file.     </td>
  </tr>
</table>

</body>
</html>