From 090b3abf8766e682c0c5558b8e3a9e86d9e9ffc3 Mon Sep 17 00:00:00 2001 From: Christopher Faylor Date: Wed, 4 Sep 2002 15:14:14 +0000 Subject: first draft --- winsup/cygwin/how-autoload-works.txt | 55 ++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 winsup/cygwin/how-autoload-works.txt diff --git a/winsup/cygwin/how-autoload-works.txt b/winsup/cygwin/how-autoload-works.txt new file mode 100644 index 0000000..a530155 --- /dev/null +++ b/winsup/cygwin/how-autoload-works.txt @@ -0,0 +1,55 @@ +Copyright 2002 Red Hat Inc., Egor Duda + +How does function autoloading work? + +Cygwin has an ability to handle win32 functions which are present on some +platforms and not present on others via autoload mechanism. It's essentially a +lazy binding of symbols. It works as following. For (almost) every function +from OS API which cygwin uses, a stub is created in file autoload.cc. Each +reference to the such function from win32 API in cygwin dll source code is +actually pointing to this stub. + +When the function, say GetConsoleWindow(), is called first time, the +control is passed to its stub. Stub tries to load appropriate system dll +via LoadModule() and get actual function address via GetProcAddress(). +If this operation succeeds, the stub is "patched" to pass control to actual +address of GetConsoleWindow() in appropriate system dll, so that next +time we won't have to load dll and perform address lookup in it again. + +If LoadModule() or GetProcAddress() fail, (and on nt4 the latter indeed +fails because GetConsoleWindow() is not available in kernel32.dll), then +application, depending on what kind of stub is created in autoload.cc, is +either: +1) Exits with fatal error. +2) Or returns a predefined value indicating an error; and sets error code to +127 (ERROR_PROC_NOT_FOUND). + +That is, almost all w32api functions are linked into cygwin dll +dynamically, at runtime. +The costs: +1) A tiny overhead in function call as each call is performed, +indirectly, via stub. +The benefits: +1) Speedup at startup time. Application only loads those dlls which are +actually needed. For example, if application never uses socket functions, +winsock dlls are never loaded. +2) Greatly simplify wincap system -- we don't need to have a separate +capability for every win32 function which may or may not be present on +particular win32 platform. +3) Allow single cygwin1.dll for all win32 platforms. + +If you're changing in cygwin1.dll source code and if you use some function that +was not used there before, you should add a stub so it will be autoloaded. To +do so, add + +LoadDLLfuncEx2 (function name, parameter block length, dll name, + non-fatality flag , value to return if function not available) + +to autoload.cc file. + +Parameter block length is a sum of sizes (in bytes) of parameters which are +being passed to the function. If non-fatality flag is set to 0, then failure +to load dll and find a function will cause fatal error. If non fatality flag +is set to 1, then call to the function will return default value. +You can also use shorter versions -- LoadDLLfuncEx and LoadDLLfunc, if the +defaults they provide suit your needs. -- cgit v1.1