The Thread Validator stub service libraries

 

The NT Service API is very simple, consisting of functions to load, start and unload the Thread Validator DLL.

 

We have also provided some debugging functions to help you debug the implementation of the NT Service API because getting data into and out of services is not always straightforward.

 

The stub service libraries used for this are shown in the following table:

 

 

All the functions exported from these libraries are exported as extern "C" so that C and C++ users can use them.

 

Library name suffixes

 

The MD suffix indicates the library was built with the /MD compiler switch.

The MT suffix indicates the library was built with the /MT compiler switch.

 

Directory Name: 2010 or 2012?

 

Visual Studio 6 to Visual Studio 2010

If you are using Visual Studio 2010 or earlier, use libraries from a directory with 2010 in the directory name.

 

Visual Studio 2010 to Visual Studio 2022

If you are using Visual Studio 2012 or later, use libraries from a directory with 2012 in the directory name.

 

 

Header files

 

The header files can be found in the svlTVStubService directory in the Thread Validator install directory.

 

The headers file provide an error enumeration and the NT Service API functions.

 

 svlTVStubService.h

 svlServiceError.h

 

 

Linker Problems

 

Some linkers cannot link the stub service library file.  If you have this problem see What do I do if I cannot use svlTVStubService.lib?

 

 

Loading the Thread Validator DLL into your service

 

To load the Thread Validator stub dll svlThreadValidatorStub(_x64).dll into your service, call svlTVStub_LoadThreadValidator(), not LoadLibrary().

 

If you are monitoring a 32 bit service with the 64 bit Thread Validator user interface you should use svlTVStub_LoadThreadValidator6432().

 

 

Shutting down the Thread Validator DLL from your service.

 

To shutdown Thread Validator's monitoring of the service , call svlTVStub_ShutdownThreadValidator().

 

This sends the shutting down notification and removes any hooks for your process.

 

Calling this function is optional. You can stop your service without calling this function.

 

 

Unloading the Thread Validator DLL from your service.

 

To unload the Thread Validator stub dll, call svlTVStub_UnloadThreadValidator(), not FreeLibrary().

 

Calling this function is optional. You can stop your service without calling this function.

 

 

Setting a service notification callback

 

Once you have successfully loaded the Thread Validator DLL you can setup a service callback so that the service control manager can be kept updated during the process of starting the validator.

 

When a service is starting, Windows requires the service to inform the Service Control Manager (SCM) that is starting at least every ten seconds.

 

Failure to do so results in Windows concluding that the service has failed to start, and the service is terminated.

 

Instrumenting your service may well take more than 10 seconds, depending on the complexity and size of your service.

 

The solution is for Thread Validator to periodically call a user supplied callback from which you can regularly inform the SCM of the appropriate status.

 

You can set the service callback with svlTVStub_SetServiceCallback(callback, userParam).

 

Usage

 

Here is an example callback which ignores the userParam.

 

   void serviceCallback(void   *userParam)
   {
       static DWORD dwCheckPoint = 1;
   
       ssStatus.dwServiceType = SERVICE_WIN32_OWN_PROCESS;
       ssStatus.dwServiceSpecificExitCode = 0;
 
       ssStatus.dwControlsAccepted = 0;
      
       ssStatus.dwCurrentState = dwCurrentState;
       ssStatus.dwWin32ExitCode = dwWin32ExitCode;
       ssStatus.dwWaitHint = dwWaitHint;
      
       ssStatus.dwCheckPoint = dwCheckPoint++;
      
       // Report the status of the service to the service control manager.
 
       return SetServiceStatus(sshStatusHandle, &ssStatus);
   }

 

 

Starting Thread Validator DLL in your service

 

To start Thread Validator detecting deadlocks in your service call svlTVStub_StartThreadValidator.

 

 

Starting Thread Validator DLL in IIS

 

To start Thread Validator detecting deadlocks in IIS call svlTVStub_StartThreadValidatorForIIS().

 

 

Setting a filename for all logging data to be written to

 

To set the filename for all debugging/logging information to be written to call svlTVStub_setLogFileName().

 

 

Deleting the logfile

 

To delete the log file call svlTVStub_deleteLogFile().

 

 

Writing text to the logfile

 

To write a standard ANSI character string to the log file call svlTVStub_writeToLogFileA(text). The ANSI string will be converted to Unicode prior to writing to the log file.
 

To write a Unicode character string to the log file call svlTVStub_writeToLogFileW(text).

 

 

Writing error code descriptions to the logfile

 

To write a human readable description of the SVL_SERVICE_ERROR error code to the log file call svlTVStub_writeToLogFile(errCode).

 

 

Writing LastError code descriptions to the logfile

 

To write a human readable description of the Windows error code to the log file call svlTVStub_writeToLogFileLastError(errCode).

 

 

Dumping the PATH environment to the logfile

 

To write the contents of the PATH environment variable to the log file call svlTVStub_dumpPathToLogFile().

 

This can be useful if you want to know what the search path is when trying to debug why a DLL wasn't found during an attempt to load the Validator DLL.