libguile/foreign.h

   1 /* Copyright (C) 2010  Free Software Foundation, Inc.
   2  *
   3  * This library is free software; you can redistribute it and/or
   4  * modify it under the terms of the GNU Lesser General Public License
   5  * as published by the Free Software Foundation; either version 3 of
   6  * the License, or (at your option) any later version.
   7  *
   8  * This library is distributed in the hope that it will be useful, but
   9  * WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  * Lesser General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public
  14  * License along with this library; if not, write to the Free Software
  15  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  16  * 02110-1301 USA
  17  */
  18
  19 #ifndef SCM_FOREIGN_H
  20 #define SCM_FOREIGN_H
  21
  22
  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_foreign_type (SCM foreign);
  93 SCM_API SCM scm_foreign_ref (SCM foreign, SCM type, SCM offset, SCM len);
  94 SCM_API SCM scm_foreign_set_x (SCM foreign, SCM val, SCM type, SCM offset);
  95
  96 SCM_INTERNAL void scm_i_foreign_print (SCM foreign, SCM port,
  97                                        scm_print_state *pstate);
  98 SCM_INTERNAL void scm_init_foreign (void);
  99
 100
 101 #endif /* SCM_FOREIGN_H */