Open topic with navigation

SK_PLUS_NetworkSemaphoreCleanup Function

Cleans-up orphaned semaphore files from a directory, which can improve the performance of SK_PLUS_NetworkSemaphoreOpen (especially when all or nearly all network seats are in use). Calling this function is also necessary when using the SK_FLAGS_NETWORK_SEMAPHORE_SKIPLOCKATTEMPT flag with SK_PLUS_NetworkSemaphoreOpen.

Remarks

The semaphorePath and semaphorePrefix parameters are required unless you have a semaphore open from a prior, successful call to SK_PLUS_NetworkSemaphoreOpen. If you provide a null or empty string after opening a semaphore, this function will automatically use the same semaphore path and prefix used to open the semaphore.

By default, this function creates a thread so the application can attempt to delete any orphaned semaphore files without experiencing any visible delay in the protected application. When using this functionality, it is important for you to test thoroughly to ensure your application is not adversely affected by the thread that is created. (For example, there are some cases where creating threads can be problematic, such as when certain or custom threading models are used. There are other cases with limitations to consider with threading, such as during DLL initialization.) The thread created by this function is automatically terminated when: this function is called again, the SK_PLUS_NetworkSemaphoreDispose function is called, or the SK_ApiContextDispose function is called.

If you have concerns about threading or network congestion, you should consider the following options for your application:

1. You can specify the SK_FLAGS_NETWORK_SEMAPHORE_NOCLEANUPTHREAD flag when calling this function. This causes the function to only attempt to delete orphaned semaphores once, and it also forces it to run synchronously (without creating any threads). This enables you to create your own implementation, which can be used to have full control over how often the application attempts to delete orphaned files, and gives you a way to run this functionality from threads your application creates and manages itself.
2. If you have concerns about orphaned semaphore files causing delays, but also have concerns about network congestion from deleting files too frequently, one option to consider is to use this function in your application with a delay of zero. This causes the function to only attempt deleting orphaned semaphore files once, which can help limit the potential for network congestion. However, with this approach, it is still possible to cause some extra congestion if a large number of users launch your application around the same time (e.g. at the start of a work day, or after lunch hours end).
3. If you have concerns about orphaned semaphore files causing delays, but also have concerns about network congestion from deleting files too frequently, another option to consider is to use this function in a separate application or service that runs on the server hosting the share. This would allow you to have a single process periodically deleting files, which allows you to avoid the concerns with congestion that can occur from having all running instances of your application attempting to delete orphaned semaphore files.

Syntax

C/C++

SK_ResultCode SK_PLUS_NetworkSemaphoreCleanup(SK_ApiContext context, int flags, const char *semaphorePath, const char *semaphorePrefix, int delay);

Visual Basic

Declare Function SK_PLUS_NetworkSemaphoreCleanup(ByVal context As Long, ByVal flags As Long, ByVal semaphorePath As String, ByVal semaphorePrefix As String, ByVal delay As Long) As Long

Arguments

context

The API Context handle.

flags

Any flags passed into this function-call.

semaphorePath

The absolute path to the directory or network share where semaphore files will be created and locked. When using a network share, a UNC-formatted path is strongly recommended.

semaphorePrefix

The prefix to use for semaphore file names.

delay

After deleting files, this is amount of time (in seconds) to wait before trying to delete orphaned semaphore files again. The value specified must be greater than or equal to 600 seconds (10 minutes), or equal to zero. Specifying zero (0) causes this function to only delete orphaned semaphore files one time. This must have a value of zero (0) when specifying the SK_FLAGS_NETWORK_SEMAPHORE_NOCLEANUPTHREAD flag.

Returns

All possible return values are included in the SK_ResultCode enumeration. Return codes to expect include: