7 Unexported Primitive Functions

▼ |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

On this page:

ffi-obj
ffi-obj?
ffi-obj-lib
ffi-obj-name
ctype-basetype
ctype-scheme->c
ctype-c->scheme
ffi-call
ffi-call-maker
ffi-callback
ffi-callback-maker
ffi-callback?
make-late-will-executor

top contents ← prev up next →

## 7 Unexported Primitive Functions🔗ℹ

Parts of the ffi/unsafe library are implemented by the Racket built-in '#%foreign module. The '#%foreign module is not intended for direct use, but it exports the following procedures (among others).

> procedure (ffi-obj objname lib) → ffi-obj?
> objname : bytes?
> lib : (or/c ffi-lib? path-string? #f)

Pulls out a foreign object from a library, returning a value that can be used as a C pointer. If lib is a path or string, then ffi-lib is used to create a library object.

> procedure (ffi-obj? x) → boolean?
> x : any/c
> (ffi-obj-lib obj) → ffi-lib?
> obj : ffi-obj?
> (ffi-obj-name obj) → bytes?
> obj : ffi-obj?

A predicate for objects returned by ffi-obj, and accessor functions that return its corresponding library object and name. These values can also be used as C pointer objects.

> procedure (ctype-basetype type) → (or/c ctype? #f)
> type : ctype?
> (ctype-scheme->c type) → procedure?
> type : ctype?
> (ctype-c->scheme type) → procedure?
> type : ctype?

Accessors for the components of a C type object, made by make-ctype. The ctype-basetype selector returns a symbol for primitive types that names the type, a list of ctypes for cstructs, and another ctype for user-defined ctypes.

> > procedure
> > (ffi-call |  | ptr |  |  |  |
> > |  | in-types |  |  |  |
> > |  | out-type |  |  |  |
> > | [ | abi |  |  |  |
> > |  | save-errno? |  |  |  |
> > |  | orig-place? |  |  |  |
> > |  | lock-name |  |  |  |
> > |  | blocking? |  |  |  |
> > |  | varargs-after]) |  | → |  | procedure?
> ptr : cpointer?
> in-types : (listof ctype?)
> out-type : ctype?
> abi : (or/c #f 'default 'stdcall 'sysv) = #f
> save-errno? : any/c = #f
> orig-place? : any/c = #f
> lock-name : (or/c #f string?) = #f
> blocking? : any/c = #f
> varargs-after : (or/c #f positive-exact-integer?) = #f

The primitive mechanism that creates Racket callout values for _cprocedure. The given ptr is wrapped in a Racket-callable primitive function that uses the types to specify how values are marshaled.

> > procedure
> > (ffi-call-maker |  | in-types |  |  |  |
> > |  | out-type |  |  |  |
> > | [ | abi |  |  |  |
> > |  | save-errno? |  |  |  |
> > |  | orig-place? |  |  |  |
> > |  | lock-name |  |  |  |
> > |  | blocking? |  |  |  |
> > |  | varargs-after]) |  | → |  | (cpointer . -> . procedure?)
> in-types : (listof ctype?)
> out-type : ctype?
> abi : (or/c #f 'default 'stdcall 'sysv) = #f
> save-errno? : any/c = #f
> orig-place? : any/c = #f
> lock-name : (or/c #f string?) = #f
> blocking? : any/c = #f
> varargs-after : (or/c #f positive-exact-integer?) = #f

A curried variant of ffi-call that takes the foreign-procedure pointer separately.

> > procedure
> > (ffi-callback |  | proc |  |  |  |
> > |  | in-types |  |  |  |
> > |  | out-type |  |  |  |
> > | [ | abi |  |  |  |
> > |  | atomic? |  |  |  |
> > |  | async-apply |  |  |  |
> > |  | varargs-after]) |  | → |  | ffi-callback?
> proc : procedure?
> in-types : any/c
> out-type : any/c
> abi : (or/c #f 'default 'stdcall 'sysv) = #f
> atomic? : any/c = #f
> async-apply : (or/c #f ((-> any) . -> . any) box?) = #f
> varargs-after : (or/c #f positive-exact-integer?) = #f

The symmetric counterpart of ffi-call. It receives a Racket procedure and creates a callback object, which can also be used as a C pointer.

> > procedure
> > (ffi-callback-maker |  | in-types |
> > |  | out-type |
> > | [ | abi |
> > |  | atomic? |
> > |  | async-apply |
> > |  | varargs-after]) |
> → (procedure? . -> . ffi-callback?)
> in-types : any/c
> out-type : any/c
> abi : (or/c #f 'default 'stdcall 'sysv) = #f
> atomic? : any/c = #f
> async-apply : (or/c #f ((-> any) . -> . any) box?) = #f
> varargs-after : (or/c #f positive-exact-integer?) = #f

A curried variant of ffi-callback that takes the callback procedure separately.

> procedure (ffi-callback? v) → boolean?
> v : any/c

A predicate for callback values that are created by ffi-callback.

> procedure (make-late-will-executor) → will-executor?

Creates a “late” will executor that readies a will for a value v only if no normal will executor has a will registered for v. In addition, for the BC implementation of Racket, normal weak references to v are cleared before a will for v is readied by the late will executor, but late weak references created by make-late-weak-box and make-late-weak-hasheq are not. For the CS implementation of Racket, a will is readied for v only when it is not reachable from any value that has a late will; if a value v is reachable from itself (i.e., through any field of v, as opposed to the immediate value itself), a “late” will for v never becomes ready.

Unlike a normal will executor, if a late will executor becomes inaccessible, the values for which it has pending wills are retained within the late will executor’s place.

A late will executor is intended for use in the implementation of register-finalizer.

top contents ← prev up next →