* libguile/deprecated.h (scm_dynamic_args_call): Deprecate.
* libguile/deprecated.c:
* libguile/dynl.h:
* libguile/dynl.c:
* doc/ref/api-foreign.texi: More doc updates.
@node Foreign Functions
@subsection Foreign Functions
+The most natural thing to do with a dynamic library is to grovel around
+in it for a function pointer: a @dfn{foreign function}.
+@code{dynamic-func} exists for that purpose.
+
@deffn {Scheme Procedure} dynamic-func name dobj
@deffnx {C Function} scm_dynamic_func (name, dobj)
Return a ``handle'' for the func @var{name} in the shared object referred to
@var{name} since it will be added automatically when necessary.
@end deffn
+Guile has static support for calling functions with no arguments,
+@code{dynamic-call}.
+
@deffn {Scheme Procedure} dynamic-call func dobj
@deffnx {C Function} scm_dynamic_call (func, dobj)
Call the C function indicated by @var{func} and @var{dobj}.
@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
@end deffn
-@deffn {Scheme Procedure} dynamic-args-call func dobj args
-@deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
-Call the C function indicated by @var{func} and @var{dobj},
-just like @code{dynamic-call}, but pass it some arguments and
-return its return value. The C function is expected to take
-two arguments and return an @code{int}, just like @code{main}:
-@smallexample
-int c_func (int argc, char **argv);
-@end smallexample
-
-The parameter @var{args} must be a list of strings and is
-converted into an array of @code{char *}. The array is passed
-in @var{argv} and its size in @var{argc}. The return value is
-converted to a Scheme number and returned from the call to
-@code{dynamic-args-call}.
-@end deffn
-
-The functions to call a function from a dynamically linked library,
-@code{dynamic-call} and @code{dynamic-args-call}, are not very powerful.
-They are mostly intended to be used for calling specially written
-initialization functions that will then add new primitives to Guile.
-For example, we do not expect that you will dynamically link
-@file{libX11} with @code{dynamic-link} and then construct a beautiful
-graphical user interface just by using @code{dynamic-call} and
-@code{dynamic-args-call}. Instead, the usual way would be to write a
-special Guile<->X11 glue library that has intimate knowledge about both
-Guile and X11 and does whatever is necessary to make them inter-operate
-smoothly. This glue library could then be dynamically linked into a
+@code{dynamic-call} is not very powerful. It is mostly intended to be
+used for calling specially written initialization functions that will
+then add new primitives to Guile. For example, we do not expect that you
+will dynamically link @file{libX11} with @code{dynamic-link} and then
+construct a beautiful graphical user interface just by using
+@code{dynamic-call}. Instead, the usual way would be to write a special
+Guile<->X11 glue library that has intimate knowledge about both Guile
+and X11 and does whatever is necessary to make them inter-operate
+smoothly. This glue library could then be dynamically linked into a
vanilla Guile interpreter and activated by calling its initialization
-function. That function would add all the new types and primitives to
+function. That function would add all the new types and primitives to
the Guile interpreter that it has to offer.
-From this setup the next logical step is to integrate these glue
-libraries into the module system of Guile so that you can load new
-primitives into a running system just as you can load new Scheme code.
+(There is actually another, better option: simply to create a
+@file{libX11} wrapper in Scheme via the dynamic FFI. @xref{Dynamic FFI},
+for more information.)
-[foreshadowing regarding dynamic ffi]
+Given some set of C extensions to Guile, the next logical step is to
+integrate these glue libraries into the module system of Guile so that
+you can load new primitives into a running system just as you can load
+new Scheme code.
@deffn {Scheme Procedure} load-extension lib init
@deffnx {C Function} scm_load_extension (lib, init)
\f
+
+
+SCM_DEFINE (scm_dynamic_args_call, "dynamic-args-call", 3, 0, 0,
+ (SCM func, SCM dobj, SCM args),
+ "Call the C function indicated by @var{func} and @var{dobj},\n"
+ "just like @code{dynamic-call}, but pass it some arguments and\n"
+ "return its return value. The C function is expected to take\n"
+ "two arguments and return an @code{int}, just like @code{main}:\n"
+ "@smallexample\n"
+ "int c_func (int argc, char **argv);\n"
+ "@end smallexample\n\n"
+ "The parameter @var{args} must be a list of strings and is\n"
+ "converted into an array of @code{char *}. The array is passed\n"
+ "in @var{argv} and its size in @var{argc}. The return value is\n"
+ "converted to a Scheme number and returned from the call to\n"
+ "@code{dynamic-args-call}.")
+#define FUNC_NAME s_scm_dynamic_args_call
+{
+ int (*fptr) (int argc, char **argv);
+ int result, argc;
+ char **argv;
+
+ if (scm_is_string (func))
+ func = scm_dynamic_func (func, dobj);
+ SCM_VALIDATE_FOREIGN_TYPED (SCM_ARG1, func, VOID);
+
+ fptr = SCM_FOREIGN_POINTER (func, void);
+
+ argv = scm_i_allocate_string_pointers (args);
+ for (argc = 0; argv[argc]; argc++)
+ ;
+ result = (*fptr) (argc, argv);
+
+ return scm_from_int (result);
+}
+#undef FUNC_NAME
+
+
+\f
+
void
scm_i_init_deprecated ()
{
/* Deprecated 2010-03-31, use array-equal? instead */
SCM_DEPRECATED SCM scm_raequal (SCM ra0, SCM ra1);
+/* Deprecated 2010-04-01, use the dynamic FFI instead */
+SCM_DEPRECATED SCM scm_dynamic_args_call (SCM symb, SCM dobj, SCM args);
+
\f
void scm_i_init_deprecated (void);
}
#undef FUNC_NAME
-SCM_DEFINE (scm_dynamic_args_call, "dynamic-args-call", 3, 0, 0,
- (SCM func, SCM dobj, SCM args),
- "Call the C function indicated by @var{func} and @var{dobj},\n"
- "just like @code{dynamic-call}, but pass it some arguments and\n"
- "return its return value. The C function is expected to take\n"
- "two arguments and return an @code{int}, just like @code{main}:\n"
- "@smallexample\n"
- "int c_func (int argc, char **argv);\n"
- "@end smallexample\n\n"
- "The parameter @var{args} must be a list of strings and is\n"
- "converted into an array of @code{char *}. The array is passed\n"
- "in @var{argv} and its size in @var{argc}. The return value is\n"
- "converted to a Scheme number and returned from the call to\n"
- "@code{dynamic-args-call}.")
-#define FUNC_NAME s_scm_dynamic_args_call
-{
- int (*fptr) (int argc, char **argv);
- int result, argc;
- char **argv;
-
- if (scm_is_string (func))
- func = scm_dynamic_func (func, dobj);
- SCM_VALIDATE_FOREIGN_TYPED (SCM_ARG1, func, VOID);
-
- fptr = SCM_FOREIGN_POINTER (func, void);
-
- argv = scm_i_allocate_string_pointers (args);
- for (argc = 0; argv[argc]; argc++)
- ;
- result = (*fptr) (argc, argv);
-
- return scm_from_int (result);
-}
-#undef FUNC_NAME
-
void
scm_init_dynamic_linking ()
{
SCM_API SCM scm_dynamic_pointer (SCM name, SCM type, SCM dobj, SCM len);
SCM_API SCM scm_dynamic_func (SCM symb, SCM dobj);
SCM_API SCM scm_dynamic_call (SCM symb, SCM dobj);
-SCM_API SCM scm_dynamic_args_call (SCM symb, SCM dobj, SCM args);
SCM_INTERNAL void scm_init_dynamic_linking (void);
projects / platform / upstream / guile.git / commitdiff