383 lines
18 KiB
HTML
383 lines
18 KiB
HTML
<?xml version="1.0" encoding="iso-8859-1" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<!--http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd-->
|
|
<html xmlns="http://www.w3.org/1999/xhtml"
|
|
>
|
|
<head><title>34 Foreign.Marshal.Utils</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
<meta name="generator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)" />
|
|
<meta name="originator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)" />
|
|
<!-- 2,html,xhtml -->
|
|
<meta name="src" content="haskell.tex" />
|
|
<meta name="date" content="2010-07-20 13:11:00" />
|
|
<link rel="stylesheet" type="text/css" href="haskell.css" />
|
|
</head><body
|
|
>
|
|
<!--l. 1--><div class="crosslinks"><p class="noindent">[<a
|
|
href="haskellch35.html" >next</a>] [<a
|
|
href="haskellch33.html" >prev</a>] [<a
|
|
href="haskellch33.html#tailhaskellch33.html" >prev-tail</a>] [<a
|
|
href="#tailhaskellch34.html">tail</a>] [<a
|
|
href="haskellpa2.html#haskellch34.html" >up</a>] </p></div>
|
|
<h2 class="chapterHead"><span class="titlemark">Chapter 34</span><br /><a
|
|
id="x42-29900034"></a><span
|
|
class="pcrr7t-">Foreign.Marshal.Utils</span></h2>
|
|
<div class="quote">
|
|
|
|
|
|
|
|
<div class="verbatim" id="verbatim-448">
|
|
module Foreign.Marshal.Utils (
|
|
 <br />    with,  new,  fromBool,  toBool,  maybeNew,  maybeWith,  maybePeek,
|
|
 <br />    withMany,  copyBytes,  moveBytes
|
|
 <br />  ) where
|
|
</div>
|
|
<p class="noindent"></div>
|
|
<h3 class="sectionHead"><span class="titlemark">34.1 </span> <a
|
|
id="x42-30000034.1"></a>General marshalling utilities </h3>
|
|
<p class="noindent">
|
|
<h4 class="subsectionHead"><span class="titlemark">34.1.1 </span> <a
|
|
id="x42-30100034.1.1"></a>Combined allocation and marshalling </h4>
|
|
<p class="noindent">
|
|
<dl> <dt class="haddockdesc">
|
|
<!--tex4ht:inline--><div class="tabular"> <table id="TBL-559" class="tabular"
|
|
cellspacing="0" cellpadding="0" rules="groups"
|
|
><colgroup id="TBL-559-1g"><col
|
|
id="TBL-559-1" /></colgroup><tr
|
|
style="vertical-align:baseline;" id="TBL-559-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-559-1-1"
|
|
class="td11"><span
|
|
class="pcrb7t-">with</span><span
|
|
class="pcrb7t-"> ::</span><span
|
|
class="pcrb7t-"> Storable</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> =></span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> (Ptr</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> b)</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> b </span></td>
|
|
</tr></table> </div> <dd class="haddockdesc">
|
|
<span
|
|
class="pcrr7t-">with</span><span
|
|
class="pcrr7t-"> val</span><span
|
|
class="pcrr7t-"> f </span>executes the computation <span
|
|
class="pcrr7t-">f</span>, passing as argument a pointer to a temporarily allocated
|
|
block of memory into which <span
|
|
class="pcrr7t-">val </span>has been marshalled (the combination of <span
|
|
class="pcrr7t-">alloca</span><a
|
|
id="dx42-301001"></a> and <span
|
|
class="pcrr7t-">poke</span><a
|
|
id="dx42-301002"></a>).
|
|
<p class="noindent"> The memory is freed when <span
|
|
class="pcrr7t-">f </span>terminates (either normally or via an exception), so the pointer passed
|
|
to <span
|
|
class="pcrr7t-">f </span>must <span
|
|
class="ptmri7t-">not </span>be used after this.
|
|
</dl>
|
|
<p class="noindent">
|
|
<dl> <dt class="haddockdesc">
|
|
<!--tex4ht:inline--><div class="tabular"> <table id="TBL-560" class="tabular"
|
|
cellspacing="0" cellpadding="0" rules="groups"
|
|
><colgroup id="TBL-560-1g"><col
|
|
id="TBL-560-1" /></colgroup><tr
|
|
style="vertical-align:baseline;" id="TBL-560-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-560-1-1"
|
|
class="td11"><span
|
|
class="pcrb7t-">new</span><span
|
|
class="pcrb7t-"> ::</span><span
|
|
class="pcrb7t-"> Storable</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> =></span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> (Ptr</span><span
|
|
class="pcrb7t-"> a) </span></td>
|
|
</tr></table> </div> <dd class="haddockdesc">
|
|
Allocate a block of memory and marshal a value into it (the combination of <span
|
|
class="pcrr7t-">malloc</span><a
|
|
id="dx42-301003"></a> and <span
|
|
class="pcrr7t-">poke</span><a
|
|
id="dx42-301004"></a>). The
|
|
size of the area allocated is determined by the <span
|
|
class="pcrr7t-">Foreign.Storable.sizeOf </span>method from the
|
|
instance of <span
|
|
class="pcrr7t-">Storable</span><a
|
|
id="dx42-301005"></a> for the appropriate type.
|
|
<p class="noindent"> The memory may be deallocated using <span
|
|
class="pcrr7t-">Foreign.Marshal.Alloc.free </span>or
|
|
<span
|
|
class="pcrr7t-">Foreign.Marshal.Alloc.finalizerFree </span>when no longer required.
|
|
</dl>
|
|
<p class="noindent">
|
|
<h4 class="subsectionHead"><span class="titlemark">34.1.2 </span> <a
|
|
id="x42-30200034.1.2"></a>Marshalling of Boolean values (non-zero corresponds to <span
|
|
class="pcrr7t-">True</span>) </h4>
|
|
<p class="noindent">
|
|
|
|
|
|
|
|
<dl> <dt class="haddockdesc">
|
|
<!--tex4ht:inline--><div class="tabular"> <table id="TBL-561" class="tabular"
|
|
cellspacing="0" cellpadding="0" rules="groups"
|
|
><colgroup id="TBL-561-1g"><col
|
|
id="TBL-561-1" /></colgroup><tr
|
|
style="vertical-align:baseline;" id="TBL-561-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-561-1-1"
|
|
class="td11"><span
|
|
class="pcrb7t-">fromBool</span><span
|
|
class="pcrb7t-"> ::</span><span
|
|
class="pcrb7t-"> Num</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> =></span><span
|
|
class="pcrb7t-"> Bool</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> a </span></td></tr></table> </div> <dd class="haddockdesc">
|
|
Convert a Haskell <span
|
|
class="pcrr7t-">Bool</span><a
|
|
id="dx42-302001"></a> to its numeric representation
|
|
</dl>
|
|
<p class="noindent">
|
|
<dl> <dt class="haddockdesc">
|
|
<!--tex4ht:inline--><div class="tabular"> <table id="TBL-562" class="tabular"
|
|
cellspacing="0" cellpadding="0" rules="groups"
|
|
><colgroup id="TBL-562-1g"><col
|
|
id="TBL-562-1" /></colgroup><tr
|
|
style="vertical-align:baseline;" id="TBL-562-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-562-1-1"
|
|
class="td11"><span
|
|
class="pcrb7t-">toBool</span><span
|
|
class="pcrb7t-"> ::</span><span
|
|
class="pcrb7t-"> Num</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> =></span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> Bool </span></td></tr></table> </div> <dd class="haddockdesc">
|
|
Convert a Boolean in numeric representation to a Haskell value
|
|
</dl>
|
|
<p class="noindent">
|
|
<h4 class="subsectionHead"><span class="titlemark">34.1.3 </span> <a
|
|
id="x42-30300034.1.3"></a>Marshalling of Maybe values </h4>
|
|
<p class="noindent">
|
|
<dl> <dt class="haddockdesc">
|
|
<!--tex4ht:inline--><div class="tabular"> <table id="TBL-563" class="tabular"
|
|
cellspacing="0" cellpadding="0" rules="groups"
|
|
><colgroup id="TBL-563-1g"><col
|
|
id="TBL-563-1" /></colgroup><tr
|
|
style="vertical-align:baseline;" id="TBL-563-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-563-1-1"
|
|
class="td11"><span
|
|
class="pcrb7t-">maybeNew</span><span
|
|
class="pcrb7t-"> ::</span><span
|
|
class="pcrb7t-"> (a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> (Ptr</span><span
|
|
class="pcrb7t-"> a))</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> Maybe</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> (Ptr</span><span
|
|
class="pcrb7t-"> a) </span></td>
|
|
</tr></table> </div> <dd class="haddockdesc">
|
|
Allocate storage and marshal a storable value wrapped into a <span
|
|
class="pcrr7t-">Maybe</span><a
|
|
id="dx42-303001"></a>
|
|
<ul class="itemize1">
|
|
<li class="itemize">the <span
|
|
class="pcrr7t-">nullPtr</span><a
|
|
id="dx42-303002"></a> is used to represent <span
|
|
class="pcrr7t-">Nothing</span><a
|
|
id="dx42-303003"></a>
|
|
</li></ul>
|
|
</dl>
|
|
<p class="noindent">
|
|
<dl><dt class="haddockdesc">
|
|
<!--tex4ht:inline--><div class="tabular"> <table id="TBL-564" class="tabular"
|
|
cellspacing="0" cellpadding="0" rules="groups"
|
|
><colgroup id="TBL-564-1g"><col
|
|
id="TBL-564-1" /></colgroup><tr
|
|
style="vertical-align:baseline;" id="TBL-564-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-564-1-1"
|
|
class="td11"><span
|
|
class="pcrb7t-">maybeWith</span><span
|
|
class="pcrb7t-"> ::</span><span
|
|
class="pcrb7t-"> (a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> (Ptr</span><span
|
|
class="pcrb7t-"> b</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> c)</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> c) </span></td>
|
|
</tr><tr
|
|
style="vertical-align:baseline;" id="TBL-564-2-"><td style="white-space:nowrap; text-align:left;" id="TBL-564-2-1"
|
|
class="td11"><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> </span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> Maybe</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> (Ptr</span><span
|
|
class="pcrb7t-"> b</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> c)</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> c </span></td>
|
|
</tr></table> </div> <dd class="haddockdesc">
|
|
Converts a <span
|
|
class="pcrr7t-">withXXX </span>combinator into one marshalling a value wrapped into a <span
|
|
class="pcrr7t-">Maybe</span><a
|
|
id="dx42-303004"></a>, using
|
|
<span
|
|
class="pcrr7t-">nullPtr</span><a
|
|
id="dx42-303005"></a> to represent <span
|
|
class="pcrr7t-">Nothing</span><a
|
|
id="dx42-303006"></a>.
|
|
</dl>
|
|
<p class="noindent">
|
|
<dl> <dt class="haddockdesc">
|
|
<!--tex4ht:inline--><div class="tabular"> <table id="TBL-565" class="tabular"
|
|
cellspacing="0" cellpadding="0" rules="groups"
|
|
><colgroup id="TBL-565-1g"><col
|
|
id="TBL-565-1" /></colgroup><tr
|
|
style="vertical-align:baseline;" id="TBL-565-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-565-1-1"
|
|
class="td11"><span
|
|
class="pcrb7t-">maybePeek</span><span
|
|
class="pcrb7t-"> ::</span><span
|
|
class="pcrb7t-"> (Ptr</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> b)</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> Ptr</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> (Maybe</span><span
|
|
class="pcrb7t-"> b) </span></td>
|
|
</tr></table> </div> <dd class="haddockdesc">
|
|
Convert a peek combinator into a one returning <span
|
|
class="pcrr7t-">Nothing</span><a
|
|
id="dx42-303007"></a> if applied to a <span
|
|
class="pcrr7t-">nullPtr</span><a
|
|
id="dx42-303008"></a>
|
|
</dl>
|
|
|
|
|
|
|
|
<p class="noindent">
|
|
<h4 class="subsectionHead"><span class="titlemark">34.1.4 </span> <a
|
|
id="x42-30400034.1.4"></a>Marshalling lists of storable objects </h4>
|
|
<p class="noindent">
|
|
<dl> <dt class="haddockdesc">
|
|
<!--tex4ht:inline--><div class="tabular"> <table id="TBL-566" class="tabular"
|
|
cellspacing="0" cellpadding="0" rules="groups"
|
|
><colgroup id="TBL-566-1g"><col
|
|
id="TBL-566-1" /></colgroup><tr
|
|
style="vertical-align:baseline;" id="TBL-566-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-566-1-1"
|
|
class="td11"><span
|
|
class="pcrb7t-">withMany</span><span
|
|
class="pcrb7t-"> ::</span><span
|
|
class="pcrb7t-"> (a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> (b</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> res)</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> res)</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> [a]</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> ([b]</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> res)</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> res </span></td>
|
|
</tr></table> </div> <dd class="haddockdesc">
|
|
Replicates a <span
|
|
class="pcrr7t-">withXXX </span>combinator over a list of objects, yielding a list of marshalled objects
|
|
</dl>
|
|
<p class="noindent">
|
|
<h4 class="subsectionHead"><span class="titlemark">34.1.5 </span> <a
|
|
id="x42-30500034.1.5"></a>Haskellish interface to memcpy and memmove </h4>
|
|
<p class="noindent"> (argument order: destination, source)
|
|
<p class="noindent">
|
|
<dl> <dt class="haddockdesc">
|
|
<!--tex4ht:inline--><div class="tabular"> <table id="TBL-567" class="tabular"
|
|
cellspacing="0" cellpadding="0" rules="groups"
|
|
><colgroup id="TBL-567-1g"><col
|
|
id="TBL-567-1" /></colgroup><tr
|
|
style="vertical-align:baseline;" id="TBL-567-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-567-1-1"
|
|
class="td11"><span
|
|
class="pcrb7t-">copyBytes</span><span
|
|
class="pcrb7t-"> ::</span><span
|
|
class="pcrb7t-"> Ptr</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> Ptr</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> Int</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> () </span></td>
|
|
</tr></table> </div> <dd class="haddockdesc">
|
|
Copies the given number of bytes from the second area (source) into the first (destination); the copied
|
|
areas may <span
|
|
class="ptmri7t-">not </span>overlap
|
|
</dl>
|
|
<p class="noindent">
|
|
<dl> <dt class="haddockdesc">
|
|
<!--tex4ht:inline--><div class="tabular"> <table id="TBL-568" class="tabular"
|
|
cellspacing="0" cellpadding="0" rules="groups"
|
|
><colgroup id="TBL-568-1g"><col
|
|
id="TBL-568-1" /></colgroup><tr
|
|
style="vertical-align:baseline;" id="TBL-568-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-568-1-1"
|
|
class="td11"><span
|
|
class="pcrb7t-">moveBytes</span><span
|
|
class="pcrb7t-"> ::</span><span
|
|
class="pcrb7t-"> Ptr</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> Ptr</span><span
|
|
class="pcrb7t-"> a</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> Int</span><span
|
|
class="pcrb7t-"> -></span><span
|
|
class="pcrb7t-"> IO</span><span
|
|
class="pcrb7t-"> () </span></td>
|
|
</tr></table> </div> <dd class="haddockdesc">
|
|
Copies the given number of bytes from the second area (source) into the first (destination); the copied
|
|
areas <span
|
|
class="ptmri7t-">may </span>overlap
|
|
</dl>
|
|
<!--l. 1--><div class="crosslinks"><p class="noindent">[<a
|
|
href="haskellch35.html" >next</a>] [<a
|
|
href="haskellch33.html" >prev</a>] [<a
|
|
href="haskellch33.html#tailhaskellch33.html" >prev-tail</a>] [<a
|
|
href="haskellch34.html" >front</a>] [<a
|
|
href="haskellpa2.html#haskellch34.html" >up</a>] </p></div>
|
|
<p class="noindent"> <a
|
|
id="tailhaskellch34.html"></a>
|
|
</body></html>
|