4D Doc Center : Semaphore

4D v13.4

Semaphore


Semaphore ( semaphore {; tickCount} ) -> Function result

Parameter	Type	Description
semaphore	String	Semaphore to test and set
tickCount	Longint	Maximum waiting time
Function result	Boolean	Semaphore has been successfully set (FALSE) or Semaphore was already set (TRUE)

Description

A semaphore is a flag shared among workstations (each user’s computer) or among processes on the same workstation. A semaphore simply exists or does not exist. The methods that each user is running can test for the existence of a semaphore. By creating and testing semaphores, methods can communicate between workstations.

The Semaphore function returns TRUE and does nothing if semaphore already exists. If semaphore does not exist, Semaphore creates it and returns FALSE. Only one user at a time can create a semaphore. If Semaphore returns FALSE, it means that the semaphore did not exist, but it also means that the semaphore has been set for the process in which the call has been made.

Semaphore returns FALSE if the semaphore was not set. It also returns FALSE if the semaphore is already set by the same process in which the call has been made. semaphore is limited to 255 characters, including prefixes (<>, $). If you pass a longer string, the semaphore will be tested with the truncated string.

The optional parameter tickCount allows you to specify a waiting time (in ticks) if semaphore is already set. In this case, the function will wait either for the semaphore to be freed or the waiting time to expire before returning True.

There are two types of semaphores in 4D: local semaphores and global semaphores.

A local semaphore is accessible by all processes on the same workstation and only on the workstation. A local semaphore can be created by prefixing the name of the semaphore with a dollar sign ($). You use local semaphores to monitor operations among processes executing on the same workstation. For example, a local semaphore can be used to monitor access to an interprocess array shared by all the processes in your single-user database or on the workstation.
A global semaphore is accessible to all users and all their processes. You use global semaphores to monitor operations among users of a multi-user database.

Global and local semaphores are identical in their logic. The difference resides in their scope.

In client-server mode, global semaphores are shared among all the processes running on all clients and servers. A local semaphore is only shared among the processes running on the machine where it has been created.

In 4D, global or local semaphores have the same scope because you are the only user. However, if your database is being used in both setups, make sure to use global or local semaphores depending on what you want to do.

Note: We recommend using local semaphores when you need a semaphore to manage a local aspect for a client of the application, such as the interface or an array of interprocess variables. If you use a global semaphores in this case, it would not only cause unnecessary network exchanges but could also affect other client machines unnecessarily. Using a local semaphore would avoid these undesirable side effects.

You do not use semaphores to protect record access. This is automatically done by 4D and 4D Server. Use semaphores to prevent several users from performing the same operation at the same time.

Example 1

In this example, you want to prevent two users from doing a global update of the prices in a Products table. The following method uses semaphores to manage this:

 If(Semaphore("UpdatePrices")) ` Try to create the semaphore

    ALERT("Another user is already updating prices. Retry later.")

 Else

    DoUpdatePrices ` Update all the prices

    CLEAR SEMAPHORE("UpdatePrices")) ` Clear the semaphore

 End if

Example 2

The following example uses a local semaphore. In a database with several processes, you want to maintain a To Do list. You want to maintain the list in an interprocess array and not in a table. You use a semaphore to prevent simultaneous access. In this situation, you only need to use a local semaphore, because your To Do list is only for your use.

The interprocess array is initialized in the Startup method:

ARRAY TEXT(◊ToDoList;0) ` The To Do list is initially empty

Here is the method used for adding items to the To Do list:

  ` ADD TO DO LIST project method

  ` ADD TO DO LIST ( Text )

  ` ADD TO DO LIST ( To do list item )

 C_TEXT($1)

 If(Not(Semaphore("$AccessToDoList";300)))

  ` Wait 5 seconds if the semaphore already exists

    $vlElem:=Size of array(◊ToDoList)+1

    INSERT IN ARAY(◊ToDoList;$vlElem)

    ◊ToDoList{$vlElem}:=$1

    CLEAR SEMAPHORE("$AccessToDoList") ` Clear the semaphore

 End if

You can call the above method from any process.

Example 3

This method allows you to not execute a method when a semaphore is present; the method alerts the calling method with an error code and plain text.

Syntax:

$L_Error:=Semaphore_proof(->$T_Text_error)

  // Protective structure using semaphores

 C_LONGINT($0)

 C_POINTER($1) // error message

 

  // Start of method

 C_LONGINT($L_MyError)

 $L_MyError:=1

 

 C_TEXT($T_Sema_local)

 $T_Sema_local:="$tictac"

 

 If(Semaphore($T_Sema_local;300))

  // We expected 300 ticks but the semaphore

  // was not released by the one that placed it:

  // we end up here

    $L_MyError:=-1

 

 Else

 

  // This method is only run by one process at a time

 

  // We placed the semaphore as we entered

  // so we're the only ones that can remove it

 

  // Do something

    ...

  // Then finish by removing the semaphore

    CLEAR SEMAPHORE($T_Sema_local)

 End if

 

 C_TEXT($T_Message)

 If($L_MyError=-1)

    $T_Message:="The semaphore "+$T_Sema_local+" has blocked access to the rest of the code"

 Else

    $T_Message:="OK"

 End if

 

 $0:=$L_MyError

 $1->:=$T_Message  // The calling method receives an error code and an explanation in plain text