{"id":21236642,"url":"https://github.com/markpizz/pthreads4w","last_synced_at":"2025-03-15T03:14:04.400Z","repository":{"id":151197005,"uuid":"143577986","full_name":"markpizz/pthreads4w","owner":"markpizz","description":null,"archived":false,"fork":false,"pushed_at":"2018-08-08T03:01:50.000Z","size":2805,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-21T18:50:05.678Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markpizz.png","metadata":{"files":{"readme":"README","changelog":"ChangeLog","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-05T02:41:24.000Z","updated_at":"2018-08-05T02:46:41.000Z","dependencies_parsed_at":"2023-05-10T20:00:46.454Z","dependency_job_id":null,"html_url":"https://github.com/markpizz/pthreads4w","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markpizz%2Fpthreads4w","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markpizz%2Fpthreads4w/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markpizz%2Fpthreads4w/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markpizz%2Fpthreads4w/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markpizz","download_url":"https://codeload.github.com/markpizz/pthreads4w/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243676775,"owners_count":20329434,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-21T00:13:04.053Z","updated_at":"2025-03-15T03:14:04.392Z","avatar_url":"https://github.com/markpizz.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"PTHREADS-WIN32 (A.K.A. PTHREADS4W)\n==================================\n\nPthreads-win32 is free software, distributed under the GNU Lesser\nGeneral Public License (LGPL). See the file 'COPYING.LIB' for terms\nand conditions. Also see the file 'COPYING' for information\nspecific to pthreads-win32, copyrights and the LGPL.\n\n\nWhat is it?\n-----------\n\nPthreads-win32 (a.k.a. pthreads4w) is an Open Source Software\nimplementation of the Threads component of the POSIX 1003.1c 1995\nStandard (or later) for Microsoft's Windows environment. Some functions\nfrom POSIX 1003.1b are also supported, including semaphores. Other\nrelated functions include the set of read-write lock functions. The\nlibrary also supports some of the functionality of the Open\nGroup's Single Unix specification, namely mutex types, plus some common\nand pthreads-win32 specific non-portable routines (see README.NONPORTABLE).\n\nSee the file \"ANNOUNCE\" for more information including standards\nconformance details and the list of supported and unsupported\nroutines.\n\n\nPrerequisites\n-------------\nMSVC or GNU C (MinGW or MinGW64 with AutoConf Tools)\n\tTo build from source.\n\nQueueUserAPCEx by Panagiotis E. Hadjidoukas\n\tTo support any thread cancellation in C++ library builds or\n\tto support cancellation of blocked threads in any build.\n\tThis library is not required otherwise.\n\n\tFor true async cancellation of threads (including blocked threads).\n\tThis is a DLL and Windows driver that provides pre-emptive APC\n\tby forcing threads into an alertable state when the APC is queued.\n\tBoth the DLL and driver are provided with the pthreads-win32.exe\n\tself-unpacking ZIP, and on the pthreads-win32 FTP site  (in source\n\tand pre-built forms). Currently this is a separate LGPL package to\n\tpthreads-win32. See the README in the QueueUserAPCEx folder for\n\tinstallation instructions.\n\n\tPthreads-win32 will automatically detect if the QueueUserAPCEx DLL\n\tQuserEx.DLL is available and whether the driver AlertDrv.sys is\n\tloaded. If it is not available, pthreads-win32 will simulate async\n\tcancellation, which means that it can async cancel only threads that\n\tare runnable. The simulated async cancellation cannot cancel blocked\n\tthreads.\n\n    [FOR SECURITY] To be found Quserex.dll MUST be installed in the\n\tWindows System Folder. This is not an unreasonable constraint given a\n\tdriver must also be installed and loaded at system startup.\n\n\nLibrary naming\n--------------\n\nBecause the library is being built using various exception\nhandling schemes and compilers - and because the library\nmay not work reliably if these are mixed in an application,\neach different version of the library has it's own name.\n\nPlease do not distribute your own modified versions of the library\nusing names conforming to this description. You can use the\nmakefile variable \"EXTRAVERSION\" to append your own suffix to the\nlibrary names when building and testing your library.\n\nNote 1: the incompatibility is really between EH implementations\nof the different compilers. It should be possible to use the\nstandard C version from either compiler with C++ applications\nbuilt with a different compiler. If you use an EH version of\nthe library, then you must use the same compiler for the\napplication. This is another complication and dependency that\ncan be avoided by using only the standard C library version.\n\nNote 2: if you use a standard C pthread*.dll with a C++\napplication, then any functions that you define that are\nintended to be called via pthread_cleanup_push() must be\n__cdecl.\n\nNote 3: the intention was to also name either the VC or GC\nversion (it should be arbitrary) as pthread.dll, including\npthread.lib and libpthread.a as appropriate. This is no longer\nlikely to happen.\n\nNote 4: the compatibility number (major version number) was\nadded so that applications can differentiate between binary\nincompatible versions of the libs and dlls.\n\nIn general the naming format used is:\n    pthread[VG]{SE,CE,C}[c][E].dll\n    pthread[VG]{SE,CE,C}[c][E].lib\n\nwhere:\n    [VG] indicates the compiler\n        V\t- MS VC, or\n        G\t- GNU C\n\n    {SE,CE,C} indicates the exception handling scheme\n        SE\t- Structured EH, or\n        CE\t- C++ EH, or\n        C\t- no exceptions - uses setjmp/longjmp\n\n        c\t- DLL major version number indicating ABI\n              compatibility with applications built against\n              a snapshot with the same major version number.\n              See 'Version numbering' below.\n        E\t- EXTRAVERSION suffix.\n\nThe name may also be suffixed by a 'd' to indicate a debugging version\nof the library. E.g. pthreadVC2d.lib. These will be created e.g. when\nthe *-debug makefile targets are used.\n\nExamples:\n\tpthreadVC2.dll\t    (MSVC/not dependent on exceptions - not binary\n                         compatible with pthreadVC1.dll or pthreadVC.dll)\n    pthreadGC2-w32.dll  (As built, e.g., by \"make GC ARCH=-m32 EXTRAVERSION=-w32\")\n    pthreadVC2-w64.dll  (As built, e.g., by \"nmake VC ARCH=-m64 EXTRAVERSION=-w64\")\n\nFor information on ARCH (MinGW GNUmakefile) or TARGET_CPU (MSVS Makefile)\nsee the respective \"Building with ...\" sections below.\n\nThe GNU library archive file names have correspondingly changed, e.g.:\n\n\tlibpthreadGCE2.a\n\tlibpthreadGC2.a\n\tlibpthreadGC2-w64.a\n\n\nVersion numbering\n-----------------\n\nSee pthread.h and the resource file 'version.rc'.\n\nMicrosoft version numbers use 4 integers:\n\n\t0.0.0.0\n\nPthreads-win32 uses the first 3 following the standard major.minor.micro\nsystem. We had claimed to follow the Libtool convention but this has\nnot been the case with recent releases. Binary compatibility and\nconsequently library file naming has not changed over this time either\nso it should not cause any problems.\n\nNOTE: Changes to the platform ABI can cause the library ABI to change\nand the current version numbering system does not account for this.\n\nThe fourth is commonly used for the build number, but will be reserved\nfor future use.\n\n\tmajor.minor.micro.0\n\nThe numbers are changed as follows:\n\n1. If the general binary interface (ABI) has changed at all since the\n   last update in a way that requires recompilation and relinking of\n   applications, then increment Major, and set both minor and micro to 0.\n   (`M:m:u' becomes `M+1:0:0')\n2. If the general API has changed at all since the last update or\n   there have been semantic/behaviour changes (bug fixes etc) but does\n   not require recompilation of existing applications, then increment\n   minor and set micro to 0.\n   (`M:m:u' becomes `M:m+1:0')\n3. If there have been no interface or semantic changes since the last\n   public release but a new release is deemed necessary for some reason,\n   then increment micro.\n   (`M:m:u' becomes `M:m:u+1')\n\n\nDLL compatibility numbering is an attempt to ensure that applications\nalways load a compatible pthreads-win32 DLL by using a DLL naming system\nthat is consistent with the version numbering system. It also allows\nolder and newer DLLs to coexist in the same filesystem so that older\napplications can continue to be used. For pre .NET Windows systems,\nthis inevitably requires incompatible versions of the same DLLs to have\ndifferent names.\n\nPthreads-win32 has adopted the Cygwin convention of appending a single\ninteger number to the DLL name. The number used is simply the library's\nmajor version number.\n\nConsequently, DLL name/s will only change when the DLL's\nbackwards compatibility changes. Note that the addition of new\n'interfaces' will not of itself change the DLL's compatibility for older\napplications.\n\n\nWhich of the several dll versions to use?\n-----------------------------------------\nor,\n---\nWhat are all these pthread*.dll and pthread*.lib files?\n-------------------------------------------------------\n\nSimple, use either pthreadGCc.* if you use GCC, or pthreadVCc.* if you\nuse MSVC - where 'c' is the DLL versioning (compatibility) number.\n\nOtherwise, you need to choose carefully and know WHY.\n\nThe most important choice you need to make is whether to use a\nversion that uses exceptions internally, or not. There are versions\nof the library that use exceptions as part of the thread\ncancellation and exit implementation. The default version uses\nsetjmp/longjmp.\n\nIf you use either pthreadVCE[2] or pthreadGCE[2]:\n\n1. [See also the discussion in the FAQ file - Q2, Q4, and Q5]\n\nIf your application contains catch(...) blocks in your POSIX\nthreads then you will need to replace the \"catch(...)\" with the macro\n\"PtW32Catch\", eg.\n\n\t#ifdef PtW32Catch\n\t\tPtW32Catch {\n\t\t\t...\n\t\t}\n\t#else\n\t\tcatch(...) {\n\t\t\t...\n\t\t}\n\t#endif\n\nOtherwise neither pthreads cancellation nor pthread_exit() will work\nreliably when using versions of the library that use C++ exceptions\nfor cancellation and thread exit.\n\nNB: [lib]pthreadGCE[2] does not support asynchronous cancellation. Any\nattempt to cancel a thread set for asynchronous cancellation using\nthis version of the library will cause the applicaton to terminate.\nWe believe this is due to the \"unmanaged\" context switch that is\ndisrupting the stack unwinding mechanism and which is used\nto cancel blocked threads. See pthread_cancel.c\n\n\nOther name changes\n------------------\n\nAll snapshots prior to and including snapshot 2000-08-13\nused \"_pthread_\" as the prefix to library internal\nfunctions, and \"_PTHREAD_\" to many library internal\nmacros. These have now been changed to \"ptw32_\" and \"PTW32_\"\nrespectively so as to not conflict with the ANSI standard's\nreservation of identifiers beginning with \"_\" and \"__\" for\nuse by compiler implementations only.\n\nIf you have written any applications and you are linking\nstatically with the pthreads-win32 library then you may have\nincluded a call to _pthread_processInitialize. You will\nnow have to change that to ptw32_processInitialize.\n\n\nCleanup code default style\n--------------------------\n\nPreviously, if not defined, the cleanup style was determined automatically\nfrom the compiler used, and one of the following was defined accordingly:\n\n\t__CLEANUP_SEH\tMSVC only\n\t__CLEANUP_CXX\tC++, including MSVC++, GNU G++\n\t__CLEANUP_C\tC, including GNU GCC, not MSVC\n\nThese defines determine the style of cleanup (see pthread.h) and,\nmost importantly, the way that cancellation and thread exit (via\npthread_exit) is performed (see the routine ptw32_throw()).\n\nIn short, the exceptions versions of the library throw an exception\nwhen a thread is canceled, or exits via pthread_exit(). This exception is\ncaught by a handler in the thread startup routine, so that the\nthe correct stack unwinding occurs regardless of where the thread\nis when it's canceled or exits via pthread_exit().\n\nIn this snapshot, unless the build explicitly defines (e.g. via a\ncompiler option) __CLEANUP_SEH, __CLEANUP_CXX, or __CLEANUP_C, then\nthe build NOW always defaults to __CLEANUP_C style cleanup. This style\nuses setjmp/longjmp in the cancellation and pthread_exit implementations,\nand therefore won't do stack unwinding even when linked to applications\nthat have it (e.g. C++ apps). This is for consistency with most/all\ncommercial Unix POSIX threads implementations.\n\nAlthough it was not clearly documented before, it is still necessary to\nbuild your application using the same __CLEANUP_* define as was\nused for the version of the library that you link with, so that the\ncorrect parts of pthread.h are included. That is, the possible\ndefines require the following library versions:\n\n\t__CLEANUP_SEH\tpthreadVSE.dll\n\t__CLEANUP_CXX\tpthreadVCE.dll or pthreadGCE.dll\n\t__CLEANUP_C\tpthreadVC.dll or pthreadGC.dll\n\nIt is recommended that you let pthread.h use it's default __CLEANUP_C\nfor both library and application builds. That is, don't define any of\nthe above, and then link with pthreadVC.lib (MSVC or MSVC++) and\nlibpthreadGC.a (MinGW GCC or G++). The reason is explained below, but\nanother reason is that the prebuilt pthreadVCE.dll is currently broken.\nVersions built with MSVC++ later than version 6 may not be broken, but I\ncan't verify this yet.\n\nWHY ARE WE MAKING THE DEFAULT STYLE LESS EXCEPTION-FRIENDLY?\nBecause no commercial Unix POSIX threads implementation allows you to\nchoose to have stack unwinding. Therefore, providing it in pthread-win32\nas a default is dangerous. We still provide the choice but unless\nyou consciously choose to do otherwise, your pthreads applications will\nnow run or crash in similar ways irrespective of the pthreads platform\nyou use. Or at least this is the hope.\n\n\nDevelopment Build Toolchains and Configurations\n-----------------------------------------------\n\nAs of Release 2.10 all build configurations pass the full test suite\nfor the following toolchains and configurations:\n\nAll DLL and static library build targets enabled in the makefiles:\nVC, VCE, VSE (DLL, inlined statics only)\nGC, GCE (DLL, inlined and small statics)\n\nMSVS:\nIntel Core i7 (6 Core HT)\nWindows 7 64 bit\nMSVS 2010 Express with SDK 7.1 (using the SDK command shell TARGET_CPU = x64 or x86)\nMSVS 2013 Express Cross Tools for x64 Command Prompt\nMSVS 2013 Express Native Tools for x32 Command Prompt\n\nGNU:\nIntel Core i7 (6 Core HT)\nWindows 7 64 bit\nMinGW64 multilib enabled (ARCH = -m64 or -m32)\nMinGW64 multilib disabled\n\n\nBuilding with MS Visual Studio (C, VC++ using C++ EH, or Structured EH)\n-----------------------------------------------------------------------\n\nNOTE: A VS project/solution/whatever file is included as a contributed\nwork and is not used of maintained in development. All building and\ntesting is done using makefiles. We use the native make system for each\ntoolchain, which is 'nmake' in this case.\n\nFrom the source directory run nmake without any arguments to list\nhelp information. E.g.\n\n$ nmake\n\nAs examples, as at Release 2.10 the pre-built DLLs and static libraries\ncan be built using one of the following command-lines:\n\n[Note: \"setenv\" comes with the SDK which is not required to build the library.\nI use it to build and test both 64 and 32 bit versions of the library.\n\"/2003\" is used to override my build system which is Win7 (at the time of\nwriting) for backwards compatibility.]\n\n$ setenv /x64 /2003 /Release\n$ nmake realclean VC\n$ nmake realclean VCE\n$ nmake realclean VSE\n$ nmake realclean VC-static\n$ nmake realclean VCE-static\n$ nmake realclean VSE-static\n$ setenv /x86 /2003 /Release\n$ nmake realclean VC\n$ nmake realclean VCE\n$ nmake realclean VSE\n$ nmake realclean VC-static\n$ nmake realclean VCE-static\n$ nmake realclean VSE-static\n\nIf you want to differentiate or customise library naming you can use,\ne.g.:\n\n$ nmake realclean VC EXTRAVERSION=\"-w64\"\n\nThe string provided via the variable EXTRAVERSION is appended to the dll\nand .lib library names, e.g.:\n\npthreadVC2-w64.dll\npthreadVC2-w64.lib\n\nTo build and test all DLLs and static lib compatibility versions\n(VC, VCE, VSE):\n\n$ setenv /x64 /2003 /release\n$ nmake all-tests\n\nYou can run the testsuite by changing to the \"tests\" directory and\nrunning nmake. E.g.:\n\n$ cd tests\n$ nmake VC\n\nNote: the EXTRAVERSION=\"...\" option is passed to the tests Makefile\nwhen you target \"all-tests\". If you build the library then change to the\ntests directory to run the tests you will need to repeat the option\nexplicitly to the test \"nmake\" command-line.\n\nFor failure analysis etc. individual tests can be built\nand run, e.g:\n\n$ cd tests\n$ nmake VC TESTS=\"foo bar\"\n\nThis builds and runs all prerequisite tests as well as the individual\ntests listed. Prerequisite tests are defined in tests\\runorder.mk.\n\nTo build and run only the tests listed use:\n\n$ cd tests\n$ nmake VC NO_DEPS=1 TESTS=\"foo bar\"\n\n\nBuilding with MinGW\n-------------------\n\nNOTE: All building and testing is done using makefiles. We use the native\nmake system for each toolchain, which is 'make' in this case.\n\nWe have found that Mingw builds of the GCE library variants can fail when\nrun on 64 bit systems, believed to be due to the DWARF2 exception handling\nbeing a 32 bit mechanism. The GC variants are fine. MinGW64 offers\nSJLJ or SEH exception handling so choose one of those.\n\nFrom the source directory:\n\nrun 'autoheader' to rewrite the config.h file\nrun 'autoconf' to rewrite the GNUmakefiles (library and tests)\nrun './configure' to create config.h and GNUmakefile.\nrun 'make' without arguments to list possible targets.\n\nE.g.\n\n$ autoheader\n$ autoconf\n$ ./configure\n$ make realclean all-tests\n\nWith MinGW64 multilib installed the following variables can be defined\neither on the make command line or in the shell environment:\n\nARCH\n - possible values are \"-m64\" and \"-m32\". You will probably recognise\n   these as gcc flags however the GNUmakefile also converts these into\n   the appropriate windres options when building version.o.\n\nAs examples, as at Release 2.10 the pre-built DLLs and static libraries\nare built from the following command-lines:\n\n$ nmake realclean GC ARCH=-m64\n$ nmake realclean GC ARCH=-m32\n$ nmake realclean GCE ARCH=-m64\n$ nmake realclean GCE ARCH=-m32\n$ nmake realclean GC-static ARCH=-m64\n$ nmake realclean GC-static ARCH=-m32\n$ nmake realclean GCE-static ARCH=-m64\n$ nmake realclean GCE-static ARCH=-m32\n\nIf you want to differentiate between libraries by their names you can use,\ne.g.:\n\n$ make realclean GC ARCH=\"-m64\" EXTRAVERSION=\"-w64\"\n\nThe string provided via the variable EXTRAVERSION is appended to the dll\nand .a library names, e.g.:\n\npthreadGC2-w64.dll\nlibpthreadGC2-w64.a\n\nTo build and test all DLLs and static lib compatibility variants (GC, GCE):\n\n$ make all-tests\nor, with MinGW64 (multilib enabled):\n$ make all-tests ARCH=-m64\n$ make all-tests ARCH=-m32\n\nYou can run the testsuite by changing to the \"tests\" directory and\nrunning make. E.g.:\n\n$ cd tests\n$ make GC\n\nNote that the ARCH=\"...\" and/or EXTRAVERSION=\"...\" options are passed to the\ntests GNUmakefile when you target \"all-tests\". If you change to the tests\ndirectory and run the tests you will need to repeat those options explicitly\nto the test \"make\" command-line.\n\nFor failure analysis etc. individual tests can be built and run, e.g:\n\n$ cd tests\n$ make GC TESTS=\"foo bar\"\n\nThis builds and runs all prerequisite tests as well as the individual\ntests listed. Prerequisite tests are defined in tests\\runorder.mk.\n\nTo build and run only those tests listed use:\n\n$ cd tests\n$ make GC NO_DEPS=1 TESTS=\"foo bar\"\n\n\nBuilding under Linux using the MinGW cross development tools\n------------------------------------------------------------\n\nYou can build the library on Linux by using the MinGW cross development\ntoolchain. See http://www.libsdl.org/extras/win32/cross/ for tools and\ninfo. The GNUmakefile contains some support for this, for example:\n\nmake CROSS=i386-mingw32msvc- clean GC\n\nwill build pthreadGCn.dll and libpthreadGCn.a (n=version#), provided your\ncross-tools/bin directory is in your PATH (or use the cross-make.sh script\nat the URL above).\n\n\nBuilding the library as a statically linkable library\n-----------------------------------------------------\n\nGeneral: PTW32_STATIC_LIB must be defined for both the library build and the\napplication build. The makefiles supplied and used by the following 'make'\ncommand lines will define this for you.\n\nMSVC (creates pthreadVCn.lib as a static link lib):\n\nnmake clean VC-static\n\n\nMinGW32 (creates libpthreadGCn.a as a static link lib):\n\nmake clean GC-static\n\nDefine PTW32_STATIC_LIB also when building your application.\n\nBuilding the library under Cygwin\n---------------------------------\n\nCygwin implements it's own POSIX threads routines and these\nwill be the ones to use if you develop using Cygwin.\n\nBuilding applications\n---------------------\n\nThe files you will need for your application build are:\n\nThe four header files:\n\t_ptw32.h\n\tpthread.h\n\tsemaphore.h\n\tsched.h\n\nThe DLL library files that you built:\n\tpthread*.dll\n\tplus the matching *.lib (MSVS) or *.a file (GNU)\n\nor, the static link library that you built:\n\tpthread*.lib (MSVS) or libpthread*.a (GNU)\n\nPlace them in the appropriate directories for your build, which may be the\nstandard compiler locations or, locations specific to your project (you\nmight have a separate third-party dependency tree for example).\n\nAcknowledgements\n----------------\n\nSee the ANNOUNCE file for acknowledgements.\nSee the 'CONTRIBUTORS' file for the list of contributors.\n\nAs much as possible, the ChangeLog file attributes\ncontributions and patches that have been incorporated\nin the library to the individuals responsible.\n\nFinally, thanks to all those who work on and contribute to the\nPOSIX and Single Unix Specification standards. The maturity of an\nindustry can be measured by it's open standards.\n\n----\nRoss Johnson\n\u003cross.johnson@loungebythelake.net\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkpizz%2Fpthreads4w","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkpizz%2Fpthreads4w","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkpizz%2Fpthreads4w/lists"}