Release Notes - Win32 Tools Library

You might also be interested in the release notes for the libraries that this one is built on:

• Admin
• C++ Tools (this was a separate library prior to version 6.0 at which point it was merged with the Win32 Tools Library

Version 6.0

• The C++Tools and RegistryTools libraries have been merged with this library. All code that used to be in these libraries and their associated namespaces are now in the JetByteTools::Win32 namespace.
• Breaking Changes to how we share a pool of critical sections; see below and see here: http://www.lenholgate.com/archives/000825.html for more details.
  • Breaking Change. The functionality that was in JetByteTools::Win32::CSharedCriticalSection in previous releases of the library is now in JetByteTools::Win32::CSharedCriticalSectionFactory as this more accurately describes what the class is. JetByteTools::Win32::CSharedCriticalSection now provides functionality for a critical section that is provided by one of the critical section factorys.
  • Added the JetByteTools::Win32::ISharedCriticalSection interface which allows you to access the underlying JetByteTools::Win32::ICriticalSection interface and requires that you call JetByteTools::Win32::ISharedCriticalSection::Release() when you no longer need to use the shared lock.
  • Added JetByteTools::Win32::CSmartSharedCriticalSection which provides an RAII wrapper for JetByteTools::Win32::ISharedCriticalSection instances.
  • Breaking Change to JetByteTools::Win32::ICriticalSectionFactory, it now returns instances of JetByteTools::Win32::ISharedCriticalSection rather than JetByteTools::Win32::ICriticalSection. It also supports 'pools' of shared locks and the ability to request a shared lock from a specific pool.
  • Added a new critical section factory, JetByteTools::Win32::CUniqueCriticalSectionFactory which creates a unique instance of a critical section for each request and destroys the instance when JetByteTools::Win32::ISharedCriticalSection::Release() is called on it. This allows you to replace an instance of JetByteTools::Win32::CSharedCriticalSectionFactory with an instance of this factory to give each user of the factory its own unique critical sections. This can be useful if you find that no matter what the size of the pool the contention between users for the same, shared, lock is too great.
• Added support for JetByteTools::Win32::ICriticalSection::TryEnter().
• Breaking Change to the JetByteTools::Win32::ToString() functions in Utils.h. These have all been moved into ToString.h, though Utils.h still provides access. We have also changed how we convert numeric types to strings. Prior to this release we used std::strstream and templates and streamed the type into a string. However this requires the acquisition of a process wide lock (for accessing locales and facets) in some versions of STL which is less than ideal for multi-threaded use. From this release we default to using a custom sprintf based system to convert from numbers to strings. We also decided to change how 0 is represented in JetByteTools::Win32::ToHexString(), it's converted to 0x0 in the new code whereas it was converted to 0 in the old. JetByteTools::Win32::ToHexString() was also enhanced to allow for the user to decide if they want upper or lower case hex digits and we added JetByteTools::Win32::PointerToString() which gives a consistent represenation of pointers across 32bit and 64bit operating systems (always representing pointers as 64bit hex values). If you define JETBYTE_USE_TEMPLATE_TO_STRING as 1 in your Admin\Config.h file then you will revert to the pre version 6.0 behaviour and functionality using std::strstream. Please note that this old code is likely to be deprecated in a future release and then removed.
• JetByteTools::Win32::CTimeChangeNotificationMonitor now compiles on versions of the compiler with headers that don't include a definition of USER_TIMER_MAXIMUM.
• Added /Zm200 to the Visual Studio .Net (2002) project file as it seems to need more space for precompiled headers when compiling with STLPort. Note that you can remove this if you do not need STLPort support

Version 5.2.5

• No changes.

Version 5.2.4

• We now compile with /Wall (in VS2005 and later) to enable all warnings, even those that are disabled by default.
• Added JetByteTools::Win32::IQueueTimers::DispatchesWithoutLock() so that you can deterime at runtime the timer dispatch policy of a queue. This can be useful to impose a requirement for lock free dispatch on an instance of the timer queue that you might be given to use. Note that this would probably better be done with an interface, so that you could specify your requirements clearly...
• Added JetByteTools::Win32::IWaitable::WaitWithMessageLoop(), this lets you pump messages whilst waiting on a handle.
• Added JetByteTools::Win32::IProvideUserData::LockUserDataSlots(), this allows you to force the provider to lock itself and allow no more slots to be added.
• Added JetByteTools::Win32::CLibraryLoader::GetOptionalProcAddress() which returns null if the function doesn't exist rather than throwing an exception.
• Fixed a race condition bug in JetByteTools::Win32::CCallbackTimerQueueBase which is detailed here: http://www.lenholgate.com/archives/000803.html.
• Added JetByteTools::Win32::IListenForTimeChangeNotifications and JetByteTools::Win32::CTimeChangeNotificationMonitor to allow you to monitor WM_TIMECHANGE messages.

Version 5.2.3

• Some whitespace changes to remove incorrect tabs.
• Added JetByteTools::Win32::ICollectableThreadPool and JetByteTools::Win32::CThreadPoolCollection which allow you to dispatch items to a named thread pool to facilitate multiple thread pools for different types of work item.
• JetByteTools::Win32::CThreadPool::WaitForShutdownToComplete() now returns a bool which is true if threads were terminated forcibly rather than being allowed to shutdown cleanly.
• Added JetByteTools::Win32::CThreadPool::DisposeOfQueuedItems and JetByteTools::Win32::IThreadPoolWorkerThreadFactory::DisposeOfQueuedItemsAfterShutdown() which work together to allow you to process all work items that were held in a thread pool's queue after the pool has been shutdown. This should be used to release resources used by items that were placed into the queue but that will now never be processed.
• Corrected the data type used for JetByteTools::Win32::CIOCompletionPort timeouts.
• Added JetByteTools::Win32::CThread::StartWithPriority(), JetByteTools::Win32::CThread::EnableThreadPriorityBoost(), JetByteTools::Win32::CThread::DisableThreadPriorityBoost(), JetByteTools::Win32::CThread::ThreadPriorityBoostEnabled(), JetByteTools::Win32::CThread::SetThreadPriority() and JetByteTools::Win32::CThread::GetThreadPriority().
• Added JetByteTools::Win32::CSmartStatupInfo which takes ownership of any input or output handles supplied to it or creates the files and takes ownership of the handles if given file names.
• Added JetByteTools::Win32::CMultipleFileDeleter which is a bit like JetByteTools::Win32::CFileDeleter but for multiple files...
• Added JetByteTools::Win32::CJob, JetByteTools::Win32::CJobEventManager, JetByteTools::Win32::IMonitorJobs, JetByteTools::Win32::IManageJobEvents, JetByteTools::Win32::IHandleJobEvents, JetByteTools::Win32::IAssignProcessesToJobs and JetByteTools::Win32::CNullJobMonitor which, together, allow you to manipulate Windows Job Objects.
• Added JetByteTools::Win32::CCallbackTimerQueueEx which uses JetByteTools::Win32::IProvideTickCount64 as its time source. See here: http://www.lenholgate.com/archives/000773.html for more details.
• Changed the implementation of JetByteTools::Win32::CCallbackTimerQueue to the one that is detailed here: http://www.lenholgate.com/archives/000773.html.
• Changed JetByteTools::Win32::CThreadedCallbackTimerQueue so that you can select which underlying timer queue implementation it uses, or provide a custom one of your own, and so that you can request that it dispatches timers without holding any internal locks. Note that the default behaviour is to hold the internal lock and this behaviour is backwards compatible with the previous releases. However, in certain designs, this makes it easy for you to deadlock. If you have a lock and you hold it whilst calling into any of the timer queue functions, and you try to acquire your lock when the timer queue calls into you then you will deadlock. Not holding the internal lock during timer dispatch means that you can't deadlock when using the timer queue but the dispatch code is possibly slightly slower. This may be important to you in certain situations so we currently provide the choice. The changes are detailed here: http://www.lenholgate.com/archives/000795.html
• Added JetByteTools::Win32::CThreadedCallbackTimerQueue::SetThreadName() which allows you to change the name of the timer queue thread. This name is displayed in the Visual Studio Debugger's thread window. The constructor now sets the name of this thread to "TimerQueue" by default.
• Added JetByteTools::Win32::CThreadPool::SetThreadName() which allows you to change the name of the worker threads that are managed by the pool. The constructor now sets the name of these threads to "ThreadPool" by default.
• Added JetByteTools::Win32::CThreadPool::SetDispatchThreadName() which allows you to change the name of the dispatch thread that is used by the pool. The constructor now sets the name of this thread to "ThreadPoolDispatch" by default. Note that this must be called before calling JetByteTools::Win32::CThreadPool::Start() for it to have an effect.
• Added JetByteTools::Win32::CThreadPool::SetThreadName() which allows you to change the name of the worker threads that are managed by the pool. The constructor now sets the name of these threads to "ThreadPool" by default. Note that this must be called before calling JetByteTools::Win32::CThreadPool::Start() for it to have an effect.
• JetByteTools::Win32::CThreadPool::WorkerThread::Run() now catches exceptions of type JetByteTools::Win32::CSEHException that leak from JetByteTools::Win32::IIOCPWorkerThreadCallback::Process() and tries to shut the worker thread down cleanly; it might work in some cases.

Version 5.2.2

• The first release to be tested with BoundsChecker, hence the slew of resource leak fixes.
• Fixed a bug in JetByteTools::Win32::IsAllDigits(), it now actually works, before it always returned true.
• Fixed memory leak in JetByteTools::Win32::GetCurrentDirectory(). We were using std::auto_ptr to attempt to delete an array of memory and we need delete[] rather than delete. Now use a string for the buffer.
• Only include JetByteTools::Win32::GetSystemWow64Directory() if the underlying OS supports it. Otherwise we throw an exception.
• Fixed a memory leak in JetByteTools::Win32::GetFileVersion(). Once again we were using std::auto_ptr for an array.
• Added JetByteTools::Win32::CopyFile().
• Added JetByteTools::Win32::CreateGUIDAsString().
• Changed JetByteTools::Win32::FileExists(), JetByteTools::Win32::LoadFileAsUnicodeString(), JetByteTools::Win32::LoadFileAsStringA() to open the file with FILE_SHARE_READ access.
• Fixed a shutdown race condition in JetByteTools::Win32::CThreadPool which could have caused a thread to callback into the pool after the pool had been destroyed.
• Added JetByteTools::Win32::CThreadedCallbackTimerQueue::GetMaximumTimeout() and JetByteTools::Win32::CCallbackTimerQueue::GetMaximumTimeout().
• Changed JetByteTools::Win32::CThreadedCallbackTimerQueue::GetNextTimeout() and JetByteTools::Win32::CCallbackTimerQueue::GetNextTimeout(), they are now const.
• Fixed the bug in JetByteTools::Win32::CCallbackTimerQueue that is detailed here: http://www.lenholgate.com/archives/000771.html
• Added several methods to JetByteTools::Win32::CSystemTime. More ways to construct and more ways to access the resulting date/time.
• Added JetByteTools::Win32::CSmartHandle::GetHandle().
• Fixed a bug in JetByteTools::Win32::CSmartHandle::~CSmartHandle() which could allow the destructor to leak an exception if the close of the handle failed.
• Changed JetByteTools::Win32::CSimpleNamedPipeServer and JetByteTools::Win32::CSimpleNamedPipeClient to use JetByteTools::Win32::CSmartHandle during construction to remove any chance of resource leaks.
• Added JetByteTools::Win32::CCriticalSection::SetSpinCount().
• Added A new constructor to JetByteTools::Win32::CSharedCriticalSection to enable you to specify a spin count for the critical sections.
• Changed JetByteTools::Win32::CSemaphore so that it derives from JetByteTools::Win32::IWaitable.
• Fixed a memory leak in JetByteTools::Win32::CSecurityDescriptorAllowAll().
• Added optional boolean inheritHandles to JetByteTools::Win32::CSecurityAttributes. This defaults to false which gives the same results as before the change.
• Added JetByteTools::Win32::CProcessToken::Enabler and JetByteTools::Win32::CProcessToken::OptionalEnabler classes for enabling privileges in a RAII manner.
• Added JetByteTools::Win32::CProcessToken::IsUserAnAdmin(), JetByteTools::Win32::CProcessToken::EnablePrivilegeIfPossible(), JetByteTools::Win32::CProcessToken::DisablePrivilegeIfPossible() and JetByteTools::Win32::CProcessToken::RemovePrivilegeIfPossible().
• Added some new constructor arguments to JetByteTools::Win32::CProcess so that you can specify the flags and whether to inhreit handles or not. Also added the following methods: JetByteTools::Win32::CProcess::GetHandle(), JetByteTools::Win32::CProcess::DetatchProcess(), JetByteTools::Win32::CProcess::ResumeProcess() and JetByteTools::Win32::CProcess::GetExitCode().
• Added validation to the constructors of JetByteTools::Win32::CKernelObjectNameImpl to ensure that we never create a name that is too long.
• Fixed a bug with JetByteTools::Win32::CEnvironmentBlock. We weren't adding a terminating null to an empty environment block.
• Added JetByteTools::Win32::CDirectoryChangeMonitor.
• Fixed a memory allocation/deallocation mismatch in JetByteTools::Win32::CCommandLine where we were using a JetByteTools::Win32::CSmartHeapPointer rather than a JetByteTools::Win32::CSmartLocalPointer for the memory returned from CommandLineToArgvW().
• Added JetByteTools::Win32::CIOCompletionPort::GetHandle() and JetByteTools::Win32::CIOCompletionPort::TryAssociateDevice().
• Added JetByteTools::Win32::CFileDeleter.
• Added JetByteTools::Win32::CMD5Digest.
• Added JetByteTools::Win32::CWOW64FileSystemRedirector.

Version 5.2.1

• VS 2008 support - Adding projects and solutions and excluding warning 4627...
• This is the first release built using continuous integration, some project file fixes to fix incorrect output directories, etc so that x64 and x86 builds can be done in complete isolation.
• We no longer output ANY debug logging directly from library code. It's your choice to log if you want to.
• Added JetByteTools::Win32::IMonitorThreadPool::OnThreadPoolError() which is called when an error occurs in a thread pool
• Added JetByteTools::Win32::IIOCPWorkerThreadCallback::OnProcessException() and JetByteTools::Win32::IIOCPWorkerThreadCallback::OnThreadTerminationException() which are called when worker threads have problems.
• Added JetByteTools::Win32::CThreadedCallbackTimerQueue::OnThreadTerminationException() which is called when the worker thread dies unexpectedly.
• Fixed JetByteTools::Win32::CThreadPool where there was a bug in the code used to forcibly terminate threads if they didn't shutdown cleanly in time during a shutdown of the pool. If the pool had expanded and then contracted, or if any threads had terminated due to exceptions then there would be invalid entries in the list of threads that the pool would attempt to terminate and this could cause access violations.
• Fixed JetByteTools::Win32::GetLastErrorMessage() it no longer reports "invalid parameter" as the error message for any messages which have insertion strings...
• JetByteTools::Win32::IsGoodReadPtr() is now cross process
• Added JetByteTools::Win32::SetCurrentDirectory()
• Added JetByteTools::Win32::StripFileNameFromPathName() which does the opposite of JetByteTools::Win32::GetFileNameFromPathName(); that is, the new function returns the path without the element after the last backslash.
• Fixed JetByteTools::Win32::CThreadNameInfo to use DWORD_PTRs rather than DWORDs.
• Added JetByteTools::Win32::CThread::IsThisThread() which returns true if the calling thread is the thread represented by the thread object.
• Added JetByteTools::Win32::IConfiguration::GetShortValue().
• Fixed JetByteTools::Win32::CThreadPool where an exception thrown from Process() would prevent OnThreadPoolProcessingStopped() being called which would screw up the active thread count and lead to thread starvation.
• Added JetByteTools::Win32::IsWow64Process() which returns true if the process is an x86 process that is running under WOW64 on an x64 system.
• Added JetByteTools::Win32::Is64bitProcess() which returns true if the process is an x64 process.
• Added JetByteTools::Win32::Is32bitProcess() which returns true if the process is an x86 process.
• Added JetByteTools::Win32::IConfiguration::GetOptionalConfiguration() and JetByteTools::Win32::IConfiguration::GetOptionalConfigurations().
• Added JetByteTools::Win32::CEvent::CreationFlags and adjusted the constructors of all three event classes so that you can specify if construction should fail if a named event object already exists, or doesn't already exist. The default behaviour is to not care, which is the same as previous versions of the library.
• A few small lint related changes, as we're now running PC-Lint on the code again.
• New constructors for JetByteTools::Win32::CEvent, JetByteTools::Win32::CAutoResetEvent and JetByteTools::Win32::CManualResetEvent to enable you to specify that creation of a named event should fail if an event of that name already exists, or if an event of that name does NOT already exist.

Version 5.2

• x64 port - Some data types have changed...
• Some tightening up on const.
• Some classes now take explicit security attributes.
• The concept of 'argument groups' has been removed from JetByteTools::Win32::CCommandLine.
• JetByteTools::Win32::IIKernelObjectName now supports three new methods that allow you to query the type of name, IsGlobalName(), IsLocalName() and IsUnqualifiedName().
• Added JetByteTools::Win32::CDebugTrace and JetByteTools::Win32::CSimpleMessageLog and legitimised the concept of debug tracing. These classes work with JetByteTools::ILogMessages and JetByteTools::CMessageLog, from the C++ Tools library (I'm still not convinced that how I've split this up is "good"), and provide a pluggable log system. If you want performance you should look at JetByteTools::IO:CAsyncFileLog from the IO Tools Library.
• Added JetByteTools::Win32::IConfiguration which is just a placeholder interface for accessing hierarchical configuration data. See JetByteTools::XML::CXMLConfiguration for an example implementation over an XML file.
• Added JetByteTools::Win32::ILocalTimeProvider and JetByteTools::Win32::CLocalTimeProvider so that testing of things that use GetLocalTime() can be made easier.
• Added JetByteTools::Win32::CProcessToken, JetByteTools::Win32::CSecurityPrivilege and JetByteTools::Win32::CSecurityPrivileges which are all incomplete and unfinished.

There were no release notes for this library prior to version 5.2

---