[Technical comments for ch17
Don Stewart <dons@galois.com>**20080828065943] {
hunk ./en/ch17-ffi.xml 129
-prefix "c_", distinguishing it from more user friendly, higher level
+prefix "c_", distinguishing it from more user-friendly, higher level
hunk ./en/ch17-ffi.xml 713
+<note>
+  <title>A note about safety</title>
+
+<para>
+When making a foreign import declaration, we can optionally specify a
+"safety" level to use when making the call, using either the
+<code>safe</code> or <code>unsafe</code> keyword. A safe call is less
+efficient, but guarantees that the Haskell system can be safely called into
+from C. An "unsafe" call has far less overhead, but the C code that is called
+must not call back into Haskell.  By default foreign imports are "safe", but
+in practice it is rare for C code to call back into Haskell, so for
+efficiency we mostly use "unsafe" calls.
+</para>
+
+</note>
+
hunk ./en/ch17-ffi.xml 832
-type inside a automatically managed data structure, yielding us the
+type inside an automatically managed data structure, yielding us the
hunk ./en/ch17-ffi.xml 887
-For the user supplied parameters, we've already decided to pass compilation
+For the user-supplied parameters, we've already decided to pass compilation
hunk ./en/ch17-ffi.xml 901
-pass). The result is either an error string, or a new, compiled. regular
+pass). The result is either an error string, or a new, compiled regular
hunk ./en/ch17-ffi.xml 1050
+<para>
+However, if we know the C code is pure, why don't we just declare it as such,
+by giving it a pure type in the import declaration? For the reason that we
+have to allocate local memory for the C function to work with, which must be
+done in the IO monad, as it is a local side effect. Those effects won't
+escape the code surrounding the foreign call, though, so when wrapped, we use
+<code>unsafePerformIO</code> to reintroduce purity.
+</para>
+
hunk ./en/ch17-ffi.xml 1366
-<prompt>*Regex Data.ByteString.Char8> </prompt><userinput>match r (pack "the quick brown fox")</userinput>
+<prompt>*Regex Data.ByteString.Char8> </prompt><userinput>match r (pack "the quick brown fox") []</userinput>
hunk ./en/ch17-ffi.xml 1368
-<prompt>*Regex Data.ByteString.Char8> </prompt><userinput>match r (pack "The Quick Brown Fox")</userinput>
+<prompt>*Regex Data.ByteString.Char8> </prompt><userinput>match r (pack "The Quick Brown Fox") []</userinput>
hunk ./en/ch17-ffi.xml 1370
-<prompt>*Regex Data.ByteString.Char8> </prompt><userinput>match r (pack "What do you know about the quick brown fox?")</userinput>
+<prompt>*Regex Data.ByteString.Char8> </prompt><userinput>match r (pack "What
+  do you know about the quick brown fox?") []</userinput>
hunk ./en/ch17-ffi.xml 1382
-<prompt>*Regex Data.ByteString.Char8> </prompt><userinput>match r (pack "abxyzpqrrrabbxyyyypqAzz")</userinput>
+<prompt>*Regex Data.ByteString.Char8> </prompt><userinput>match r (pack "abxyzpqrrrabbxyyyypqAzz") []</userinput>
hunk ./en/ch17-ffi.xml 1384
+<prompt>*Regex Data.ByteString.Char8> </prompt><userinput>let Right r = compile (pack "^([^!]+)!(.+)=apquxz\\.ixr\\.zzz\\.ac\\.uk$") []</userinput>
+<prompt>*Regex Data.ByteString.Char8> </prompt><userinput>match r (pack "abc!pqr=apquxz.ixr.zzz.ac.uk") []</userinput>
+Just ["abc!pqr=apquxz.ixr.zzz.ac.uk","abc","pqr"]
}