From 3c1b716bf99a5c5432d8b3e0b04ba3d0af192be2 Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Wed, 25 Mar 2009 23:00:02 -0500 Subject: [PATCH] move a lot of words to alien.libraries --- basis/alien/libraries/authors.txt | 1 + basis/alien/libraries/libraries-docs.factor | 60 +++++++++++++++++++++ basis/alien/libraries/libraries.factor | 22 ++++++++ 3 files changed, 83 insertions(+) create mode 100644 basis/alien/libraries/authors.txt create mode 100644 basis/alien/libraries/libraries-docs.factor create mode 100644 basis/alien/libraries/libraries.factor diff --git a/basis/alien/libraries/authors.txt b/basis/alien/libraries/authors.txt new file mode 100644 index 0000000000..1901f27a24 --- /dev/null +++ b/basis/alien/libraries/authors.txt @@ -0,0 +1 @@ +Slava Pestov diff --git a/basis/alien/libraries/libraries-docs.factor b/basis/alien/libraries/libraries-docs.factor new file mode 100644 index 0000000000..3b9c56c8fb --- /dev/null +++ b/basis/alien/libraries/libraries-docs.factor @@ -0,0 +1,60 @@ +! Copyright (C) 2009 Slava Pestov. +! See http://factorcode.org/license.txt for BSD license. +USING: accessors alien alien.syntax assocs help.markup +help.syntax io.backend kernel namespaces ; +IN: alien.libraries + +HELP: +{ $values + { "path" "a pathname string" } { "abi" "the ABI used by the library, either " { $snippet "cdecl" } " or " { $snippet "stdcall" } } + { "library" library } } +{ $description "Opens a C library using the path and ABI parameters and outputs a library tuple." } +{ $notes "User code should use " { $link add-library } " so that the opened library is added to a global hashtable, " { $link libraries } "." } ; + +HELP: libraries +{ $description "A global hashtable that keeps a list of open libraries. Use the " { $link add-library } " word to construct a library and add it with a single call." } ; + +HELP: library +{ $values { "name" "a string" } { "library" "a hashtable" } } +{ $description "Looks up a library by its logical name. The library object is a hashtable with the following keys:" + { $list + { { $snippet "name" } " - the full path of the C library binary" } + { { $snippet "abi" } " - the ABI used by the library, either " { $snippet "cdecl" } " or " { $snippet "stdcall" } } + { { $snippet "dll" } " - an instance of the " { $link dll } " class; only set if the library is loaded" } + } +} ; + +HELP: dlopen ( path -- dll ) +{ $values { "path" "a pathname string" } { "dll" "a DLL handle" } } +{ $description "Opens a native library and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } "." } +{ $errors "Throws an error if the library could not be found, or if loading fails for some other reason." } +{ $notes "This is the low-level facility used to implement " { $link load-library } ". Use the latter instead." } ; + +HELP: dlsym ( name dll -- alien ) +{ $values { "name" "a C symbol name" } { "dll" "a DLL handle" } { "alien" "an alien pointer" } } +{ $description "Looks up a symbol in a native library. If " { $snippet "dll" } " is " { $link f } " looks for the symbol in the runtime executable." } +{ $errors "Throws an error if the symbol could not be found." } ; + +HELP: dlclose ( dll -- ) +{ $values { "dll" "a DLL handle" } } +{ $description "Closes a DLL handle created by " { $link dlopen } ". This word might not be implemented on all platforms." } ; + +HELP: load-library +{ $values { "name" "a string" } { "dll" "a DLL handle" } } +{ $description "Loads a library by logical name and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } ". If the library is already loaded, returns the existing handle." } ; + +HELP: add-library +{ $values { "name" "a string" } { "path" "a string" } { "abi" "one of " { $snippet "\"cdecl\"" } " or " { $snippet "\"stdcall\"" } } } +{ $description "Defines a new logical library named " { $snippet "name" } " located in the file system at " { $snippet "path" } "and the specified ABI." } +{ $notes "Because the entire source file is parsed before top-level forms are executed, " { $link add-library } " cannot be used in the same file as " { $link POSTPONE: FUNCTION: } " definitions from that library. The " { $link add-library } " call will happen too late, after compilation, and the alien calls will not work." +$nl +"Instead, " { $link add-library } " calls must either be placed in different source files from those that use that library, or alternatively, " { $link "syntax-immediate" } " can be used to load the library before compilation." } +{ $examples "Here is a typical usage of " { $link add-library } ":" +{ $code + "<< \"freetype\" {" + " { [ os macosx? ] [ \"libfreetype.6.dylib\" \"cdecl\" add-library ] }" + " { [ os windows? ] [ \"freetype6.dll\" \"cdecl\" add-library ] }" + " [ drop ]" + "} cond >>" +} +"Note the parse time evaluation with " { $link POSTPONE: << } "." } ; diff --git a/basis/alien/libraries/libraries.factor b/basis/alien/libraries/libraries.factor new file mode 100644 index 0000000000..adb9eeb1bb --- /dev/null +++ b/basis/alien/libraries/libraries.factor @@ -0,0 +1,22 @@ +! Copyright (C) 2009 Slava Pestov. +! See http://factorcode.org/license.txt for BSD license. +USING: accessors alien assocs io.backend kernel namespaces ; +IN: alien.libraries + +SYMBOL: libraries + +libraries [ H{ } clone ] initialize + +TUPLE: library path abi dll ; + +: library ( name -- library ) libraries get at ; + +: ( path abi -- library ) + over dup [ dlopen ] when \ library boa ; + +: load-library ( name -- dll ) + library dup [ dll>> ] when ; + +: add-library ( name path abi -- ) + [ dup [ normalize-path ] when ] dip + swap libraries get set-at ;