libguile/foreign.h

   1 #ifndef SCM_FOREIGN_H
   2 #define SCM_FOREIGN_H
   3
   4 /* Copyright (C) 2010  Free Software Foundation, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public License
   8  * as published by the Free Software Foundation; either version 3 of
   9  * the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19  * 02110-1301 USA
  20  */
  21
  22 #include "libguile/__scm.h"
  23
  24 /* A foreign value is some value that exists outside of Guile. It is represented
  25    by a cell whose second word is a pointer. The first word has the
  26    scm_tc7_foreign typecode and type of the aliased (pointed-to) value in its
  27    lower 16 bits.
  28
  29    There are numeric types, like uint32 and float, and there is a "generic
  30    pointer" type, void. Void pointers also have a length associated with them,
  31    in the high bits of the first word of the SCM object, but since they really
  32    are pointers out into the wild wooly world of C, perhaps we don't actually
  33    know how much memory they take up. In that, most general case, the "len"
  34    will be stored as 0.
  35
  36    The basic idea is that we can help the programmer to avoid cutting herself,
  37    but we won't take away her knives.
  38 */
  39 typedef enum
  40   {
  41     SCM_FOREIGN_TYPE_VOID, /* a pointer out into the wilderness */
  42     SCM_FOREIGN_TYPE_FLOAT,
  43     SCM_FOREIGN_TYPE_DOUBLE,
  44     SCM_FOREIGN_TYPE_UINT8,
  45     SCM_FOREIGN_TYPE_INT8,
  46     SCM_FOREIGN_TYPE_UINT16,
  47     SCM_FOREIGN_TYPE_INT16,
  48     SCM_FOREIGN_TYPE_UINT32,
  49     SCM_FOREIGN_TYPE_INT32,
  50     SCM_FOREIGN_TYPE_UINT64,
  51     SCM_FOREIGN_TYPE_INT64,
  52     SCM_FOREIGN_TYPE_LAST = SCM_FOREIGN_TYPE_INT64
  53   } scm_t_foreign_type;
  54
  55
  56 typedef void (*scm_t_foreign_finalizer) (void *);
  57
  58 #define SCM_FOREIGN_P(x)                                                \
  59   (!SCM_IMP (x) && SCM_TYP7(x) == scm_tc7_foreign)
  60 #define SCM_VALIDATE_FOREIGN(pos, x)                                    \
  61   SCM_MAKE_VALIDATE (pos, x, FOREIGN_P)
  62 #define SCM_FOREIGN_TYPE(x)                                             \
  63   ((scm_t_foreign_type)((SCM_CELL_WORD_0 (x) >> 8)&0xff))
  64 #define SCM_FOREIGN_POINTER(x, ctype)                                   \
  65   ((ctype*)SCM_CELL_WORD_1 (x))
  66 #define SCM_FOREIGN_VALUE_REF(x, ctype)                                 \
  67   (*SCM_FOREIGN_POINTER (x, ctype))
  68 #define SCM_FOREIGN_VALUE_SET(x, ctype, val)                            \
  69   (*SCM_FOREIGN_POINTER (x, ctype) = (val))
  70 #define SCM_FOREIGN_HAS_FINALIZER(x)                            \
  71   ((SCM_CELL_WORD_0 (x) >> 16) & 0x1)
  72 #define SCM_FOREIGN_LEN(x)                                              \
  73   ((size_t)(SCM_CELL_WORD_0 (x) >> 17))
  74
  75 #define SCM_FOREIGN_TYPED_P(x, type)                                    \
  76   (SCM_FOREIGN_P (x) && SCM_FOREIGN_TYPE (x) == SCM_FOREIGN_TYPE_##type)
  77 #define SCM_VALIDATE_FOREIGN_TYPED(pos, x, type)                        \
  78   do {                                                                  \
  79     SCM_ASSERT_TYPE (SCM_FOREIGN_TYPED_P (x, type), x, pos, FUNC_NAME,  \
  80                      "FOREIGN_"#type"_P");                              \
  81   } while (0)
  82
  83 #define SCM_FOREIGN_VALUE_P(x)                                          \
  84   (SCM_FOREIGN_P (x) && SCM_FOREIGN_TYPE (x) != SCM_FOREIGN_TYPE_VOID)
  85 #define SCM_VALIDATE_FOREIGN_VALUE(pos, x)                              \
  86   SCM_MAKE_VALIDATE (pos, x, FOREIGN_VALUE_P)
  87
  88 SCM_API SCM scm_take_foreign_pointer (scm_t_foreign_type type, void *ptr,
  89                                       size_t len,
  90                                       scm_t_foreign_finalizer finalizer);
  91
  92 SCM_API SCM scm_alignof (SCM type);
  93 SCM_API SCM scm_sizeof (SCM type);
  94 SCM_API SCM scm_foreign_type (SCM foreign);
  95 SCM_API SCM scm_foreign_ref (SCM foreign);
  96 SCM_API SCM scm_foreign_set_x (SCM foreign, SCM val);
  97 SCM_API SCM scm_foreign_to_bytevector (SCM foreign, SCM type,
  98                                        SCM offset, SCM len);
  99 SCM_API SCM scm_foreign_set_finalizer_x (SCM foreign, SCM finalizer);
 100 SCM_API SCM scm_bytevector_to_foreign (SCM bv, SCM offset, SCM len);
 101
 102 SCM_INTERNAL void scm_i_foreign_print (SCM foreign, SCM port,
 103                                        scm_print_state *pstate);
 104
 105 \f
 106
 107 /* Foreign functions */
 108
 109 /* The goal is to make it so that calling a foreign function doesn't cause any
 110    heap allocation. That means we need native Scheme formats for all kinds of
 111    arguments.
 112
 113    For "value" types like s64 or f32, we just use native Scheme value types.
 114    (Note that in both these cases, allocation is possible / likely, as the
 115    value might need to be boxed, but perhaps we won't worry about that. Hmm.)
 116
 117    For everything else, we use foreign pointers. This includes arrays, pointer
 118    arguments and return vals, struct args and return vals, and out and in/out
 119    arguments.
 120  */
 121
 122 SCM_API SCM scm_make_foreign_function (SCM return_type, SCM func_ptr,
 123                                        SCM arg_types);
 124 SCM_INTERNAL SCM scm_i_foreign_call (SCM foreign, SCM *argv);
 125
 126 \f
 127
 128 SCM_INTERNAL void scm_register_foreign (void);
 129
 130
 131 #endif /* SCM_FOREIGN_H */