libguile/foreign.h

   1 #ifndef SCM_FOREIGN_H
   2 #define SCM_FOREIGN_H
   3
   4 /* Copyright (C) 2010, 2011, 2012, 2013  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 pointer" is a wrapped C pointer.  It is represented by a
  25    cell whose second word is a pointer.  The first word has the
  26    `scm_tc7_pointer' type code.
  27
  28    The basic idea is that we can help the programmer to avoid cutting herself,
  29    but we won't take away her knives.  */
  30
  31 enum scm_t_foreign_type
  32   {
  33     SCM_FOREIGN_TYPE_VOID,
  34     SCM_FOREIGN_TYPE_FLOAT,
  35     SCM_FOREIGN_TYPE_DOUBLE,
  36     SCM_FOREIGN_TYPE_UINT8,
  37     SCM_FOREIGN_TYPE_INT8,
  38     SCM_FOREIGN_TYPE_UINT16,
  39     SCM_FOREIGN_TYPE_INT16,
  40     SCM_FOREIGN_TYPE_UINT32,
  41     SCM_FOREIGN_TYPE_INT32,
  42     SCM_FOREIGN_TYPE_UINT64,
  43     SCM_FOREIGN_TYPE_INT64,
  44     SCM_FOREIGN_TYPE_LAST = SCM_FOREIGN_TYPE_INT64
  45   };
  46
  47 typedef enum scm_t_foreign_type scm_t_foreign_type;
  48
  49 typedef void (*scm_t_pointer_finalizer) (void *);
  50
  51 #define SCM_POINTER_P(x) (SCM_HAS_TYP7 (x, scm_tc7_pointer))
  52 #define SCM_VALIDATE_POINTER(pos, x)            \
  53   SCM_MAKE_VALIDATE (pos, x, POINTER_P)
  54 #define SCM_POINTER_VALUE(x)                    \
  55   ((void *) SCM_CELL_WORD_1 (x))
  56
  57 SCM_API void *scm_to_pointer (SCM pointer);
  58 SCM_API SCM scm_from_pointer (void *, scm_t_pointer_finalizer);
  59
  60 SCM_API SCM scm_alignof (SCM type);
  61 SCM_API SCM scm_sizeof (SCM type);
  62 SCM_API SCM scm_pointer_address (SCM pointer);
  63 SCM_API SCM scm_pointer_to_scm (SCM pointer);
  64 SCM_API SCM scm_scm_to_pointer (SCM scm);
  65 SCM_API SCM scm_pointer_to_bytevector (SCM pointer, SCM type,
  66                                        SCM offset, SCM len);
  67 SCM_API SCM scm_set_pointer_finalizer_x (SCM pointer, SCM finalizer);
  68 SCM_API SCM scm_bytevector_to_pointer (SCM bv, SCM offset);
  69
  70 SCM_INTERNAL SCM scm_pointer_p (SCM obj);
  71 SCM_INTERNAL SCM scm_make_pointer (SCM address, SCM finalizer);
  72 SCM_INTERNAL void scm_i_pointer_print (SCM pointer, SCM port,
  73                                        scm_print_state *pstate);
  74
  75 SCM_INTERNAL SCM scm_dereference_pointer (SCM pointer);
  76 SCM_INTERNAL SCM scm_string_to_pointer (SCM string, SCM encoding);
  77 SCM_INTERNAL SCM scm_pointer_to_string (SCM pointer, SCM length, SCM encoding);
  78
  79 \f
  80
  81 /* Foreign functions */
  82
  83 /* The goal is to make it so that calling a foreign function doesn't cause any
  84    heap allocation. That means we need native Scheme formats for all kinds of
  85    arguments.
  86
  87    For "value" types like s64 or f32, we just use native Scheme value types.
  88    (Note that in both these cases, allocation is possible / likely, as the
  89    value might need to be boxed, but perhaps we won't worry about that. Hmm.)
  90
  91    For everything else, we use foreign pointers. This includes arrays, pointer
  92    arguments and return vals, struct args and return vals, and out and in/out
  93    arguments.
  94  */
  95
  96 SCM_API SCM scm_pointer_to_procedure (SCM return_type, SCM func_ptr,
  97                                       SCM arg_types);
  98 SCM_API SCM scm_procedure_to_pointer (SCM return_type, SCM func_ptr,
  99                                       SCM arg_types);
 100 SCM_INTERNAL SCM scm_i_foreign_call (SCM foreign, const SCM *argv);
 101 SCM_INTERNAL int scm_i_foreign_arity (SCM foreign,
 102                                       int *req, int *opt, int *rest);
 103
 104 \f
 105
 106 SCM_INTERNAL void scm_register_foreign (void);
 107
 108
 109 #endif /* SCM_FOREIGN_H */