Discussions on the F# List raised the broader issue of how to use C/C++ directly from F#. This is an important topic, and I wanted to give some preliminary notes in order to set expectations about the degree to which this is supported in the current release. I have also included an update of my sample that I sent in reply to his first message with the use of arrays removed, and also an additional sample showing how to pass a callback to C.

Broadly speaking, you can now do everything that you need from a C FFI interop layer from F#. On the whole things are easier than from OCaml, since you generally don’t have to write any C code, though things are a little trickier than from C#, which has added a number of conveniences to the language in order support writing “unsafe” code.

As background to these preliminary notes I would strongly recommend reading some of the tutorials on unsafe code, e.g. in the C# manual, or http://msdn.microsoft.com/library/en-us/csref/html/vcwlkunsafecodetutorial.asp. Uses of “fixed” in C# become explicit uses of a “pinned” function as shown further below.

• DllImport is the attribute used to mark a function as “external”, as in C#. It is in the namespace System.Runtime.InteropServices. The name of the function should match the name of the C entry point. CPlusPlus functions are called by using “extern C” and dllexport in the CPlusPlus code to mark them as C entrypoints. The body of methods marked DllImport is ignored. It is common practice to use the “external” idiom shown further below. The full type signature must be specified for DllImport methods, both argument types and return types. The arguments to a DllImport function can be given as either a tuple or an iterated sequence of function arguments (i.e. “curried”).

• Arguments of type int32, byte etc. can be given their natural type in the DllImport stub and passed as expected

• Pointer-typed arguments should be given the type IntPtr in the DllImport stub (equal to F#’s nativeint type). Memory management (pinning etc.) should be performed from F#. Values of type IntPtr are generally generated by using AddrOfPinnedObject on a GCHandle for a pinned value of type “obj”. This function can only be used on a limited range of “blittable” types as specified at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconcopyingpinning.asp. For example, this function can be used on a boxed integer in order to acquire the heap address of the integer.

• Buffer arguments (e.g. blobs of bytes) can be given pointer type IntPtr in the DllImport stub. to the C/C++ code then you should create an array, pin it and call AddrOfPinnedObject.

• Non-Unicode string arguments (“char *”) should currently be passed blobs of bytes appropriately pinned. The MLLib function Bytearray.string_to_ascii is useful here.

• Callback arguments (C function pointers) should be given a delegate type. This is one of the only places where you need to declare new delegate types in F# . A future release of F# may allow you to simply use F# function types and auto-fabricate the appropriate delegate types. You should call GC.KeepAlive(ctrlEventHandlers) or create a Normal GCHandle to keep your delegate value alive for the entire period in which the callback may remain active.

Here are some notes for those familiar with OCaml’s C FFI interop layer:

• The model is somewhat different: You don’t include any header files, you generally don’t write any C code, you don’t talk to the .NET GC from your C code. You generally don’t allocate .NET values from C directly (you can use a callback argument to create buffers for you). You can’t raise exceptions from C code. The DllImport mechanism is very much aimed at making existing C APIs such as the Win32 API directly accessible from .NET languages. It is not meant to allow you to write F# code from C.
• If you want to return a tuple of values from your C code you should pass in pinned reference locations which can hold the values.

Sample 1 – Using a simple function from a DLL, return results by reference

Here is an updated version of SooHyoung’s sample.

• It uses an F# 1.1 augmentation when defining the PtrRef type, which acts as a box around arguments that we pass by pointer reference – this is not essential
• You could add an assert in the PtrRef.Create method to check that the variable type “’a” is a blittable type according to the specification at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconcopyingpinning.asp

 open System
 open System.Runtime.InteropServices
 open System.Windows.Forms
 open System.Drawing




 [<DllImport("cards.dll")>]
 let cdtInit((width: IntPtr), (height: IntPtr)) : unit = ()


 let pinned (obj: obj) f = 
   let gch = GCHandle.Alloc(obj,GCHandleType.Pinned) in 
   try f(gch.AddrOfPinnedObject())
   finally
     gch.Free()


 type PtrRef<'a> = { v : obj }
   with 
     static member Create(x) = { v  = box(x) }
     member x.Value = (unbox x.v : 'a)
     member x.Pin(f) = pinned(x.v) f
   end


 let card_init () =
   let width = PtrRef.Create(300) in
   let height = PtrRef.Create(400) in
   width.Pin (fun widthAddress -> 
     height.Pin (fun heightAddress -> 
       cdtInit (widthAddress, heightAddress)));
   Printf.printf "width.(0) = %d\n" width.Value;
   Printf.printf "height.(0) = %d\n" height.Value;
   ()


 do card_init()

Sample 2 – Passing a callback value to C

 type ControlEventHandler = delegate of int -> bool


 [<DllImport("kernel32.dll")>]
 let SetConsoleCtrlHandler((callback:ControlEventHandler),(add: bool)) : unit = ()


 let CTRL_C = 0  // from Win32 C header files
 let raised = ref false
 let ctrlEventHandler = new ControlEventHandler(fun i ->  if i = CTRL_C then (raised := true; true) else  false ) 
 do SetConsoleCtrlHandler(ctrlEventHandler,true)


 // Main application goes here
 //...


 // End of main application
 //
 // We add the line below to ensure that the ctrlEventHandler is not 
 // collected while the callback may
 // be active.  A GCHandle or type Normal
 // with the appropriate lifetime can also be used.


 do GC.KeepAlive(ctrlEventHandlers)

Sample 3 - Wrapping an unmanaged array

Dmitry was wanting to access an arbitrary block of memory allocated elsewhere, so he'll need to use unverifiable IL instructions, which is of course what C# does with it's /unsafe switch. I've given a sample below to get you going - it's one of the small wonders of F# inline .NET assembly code combined with .NET generics that you can get this implemented for a huge range of data types in only 10 lines! I'll leave it to you to put together a big-array wrapper which uses the full range of phantom-type tricks to make this safe. If you need big array of non-primitive datatypes you'll need to do a little more work (you need to make structs that are blittable).

I see no real reason why the corresponding generated native code won't go as fast as C code, though that would have to be checked and maybe some minor glitches ironed out.

  /// This code is only for use with .NET 2.0 (nb. if you add 'inline'
  /// to the 'get' function it should work correctly on .NET 1.x)
  /// Also fsi.exe won't accept it entered interactively when last checked (11/02/2006)


  /// These represent unmanaged external arrays of type 'a, allocated by 
  /// some other external source, e.g. malloc. You have an obligation
  /// when creating an instance of this value to ensure that the 
  /// aent type is correct, and you also have an obligation not
  /// to access out-of bounds.
  type 'a earray = EA of nativeint 


  /// Get the address of an element in the array
  let address (EA x : 'a earray) n = 
    let size = (# "sizeof !!0" type ('a) : int32) in 
    (# "add" x (n * size) : nativeint)  


  /// Fetch a value from the unmanaged array
  let get (arr : 'a earray) n = (# "ldobj !0" type ('a) (address arr n) : 'a) 


  /// Set a value in the unmanaged array
  let set (arr : 'a earray) n (x : 'a) = (# "stobj !0" type ('a) (address arr n) x)  

Here's some sample code:

  // That's all you need to do.  The rest of this code just
  // cons's up some data and grabs the internal address using a
  // GCHandle, and tests it, then tests it on a range of types.


  open System.Runtime.InteropServices


  let data = [| 1;2;3;4 |]
  let gch = GCHandle.Alloc(data,GCHandleType.Pinned) 
  let addr = gch.AddrOfPinnedObject()


  let wrapped : int earray = EA addr 
  do printf "wrapped.(0) = %d\n" (get wrapped 0)
  do printf "wrapped.(1) = %d\n" (get wrapped 1)
  do printf "wrapped.(2) = %d\n" (get wrapped 2)
  do set wrapped 2 10067
  do printf "wrapped.(0) = %d\n" (get wrapped 0)
  do printf "wrapped.(1) = %d\n" (get wrapped 1)
  do printf "wrapped.(2) = %d\n" (get wrapped 2)

So that was all fine, except we forgot to dispose of the GC handle!

  // This standard piece of code disposes the GC handle when we leave the 
  // lexical scope.


  let pinned (obj:>obj) f = 
   let gch = GCHandle.Alloc(obj,GCHandleType.Pinned) in 
   try f(gch.AddrOfPinnedObject())
   finally
     gch.Free()


  // Now write a generic test wrapper that uses that


  let test (data : 'a[]) = 
    pinned data (fun addr -> 
      let wrapped : 'a earray = EA addr  in
      for i = 0 to Array.length data - 1 do 
        printf "wrapped.(%d) = %a\n" i output_any (get wrapped i)
      done)


  // And test it....


  do test [| 1;2;3;4 |]
  do test [| 1.0;2.0;3.0;4.0 |]
  do test [| 1.0f;2.0f;3.0f;4.0f |]
  do test (Array.map Byte.of_int [| 1;2;3;4 |])
OCaml is the ML dialect and implementation that acted as one of the inspirations for F#
7/9/2006 12:49:17 PM - -81.146.14.140
MLLib is a library that gives a good degree of compatibility with the OCaml 3.06 standard libraries
7/27/2005 6:34:40 AM - -213.199.128.147