Last modified: February 13, 2002

Description

This object oriented Perl module implements the Win32 synchronisation mechanisms: Semaphore,Mutex,Event and Timer objects.

Class hierarchy

• ISync interface

new()
Wait()
Close()

• Timer Class (Note:The timer class is only compatible with WinNT)
  
  Create
  Set
  Open
  Cancel
  
  Semaphore Class
  
  Create
  Open
  Release
  
  Mutex Class
  
  Create
  Open
  Release
  
  Event Class
  
  Create
  Open
  Reset
  Set

---

Timer Class

Index

Create($ct_Type,$Name)

Create Creates a "waitable" timer object.

$ct_Type: Specifies the timer type. If it is MANUALRESET, the timer is a manual-reset notification timer. if it is AUTORESET, the timer is a synchronization timer.

$Name: Specifies the name of the timer object.

If Create()fails, the return value will be undef .To get extended error information, call LastError().

Important note:

To avoid namespace conflicts, please use a name like //TIMER/Name

Example:

use Win32::ISync;
my($TimerObj)= new Win32::ISync::Timer;
$TimerObj->Create(AUTORESET,"//TIMER/Perl");

---

Index

Set($Date,$Time,$Period,$ct_Absolute_Relative)

Set Activates the specified "waitable" timer. When the due time arrives, the timer is signaled

$Date Specifies the date at wich the time will be signaled in "Day/DayOfWeek/Month/Year" format,If $Date is CURRENT_DATE the current date will be used by default.

$Time Specifies a time at wich the timer will be signaled in "Hour:Minute:Second:Millisecond:Microsecond:Nanosecond" format:

Hour: 0..23
Minute: 0..59
Second: 0..59
Millisecond: 0..999
Microsecond:0.999
Nanosecond:0..999

$ct_Absolute_Relative: Indicates an absolute or relative time,you can specify two values :ABSOLUTE and RELATIVE.

$Period: Period of the timer in milliseconds. A 0 period causes the timer to become signaled only once while a value greater than 0 causes the timer to periodically become signaled.

This can also be a mutiple of the following constants: _1SEC,_1MIN,_1HOUR,_1DAY,_1WEEK..

Note that a periodic manual-reset timer remains in the signaled state until it is explicitly reset.

If the Set()fails, the return value will be undef .To get extended error information, call LastError().

Example1:

my($TimerObj)= new Win32::ISync::Timer;
$TimerObj->Create(AUTORESET,"//TIMER/perl");
$TimerObj->Set(CURRENT_DATE,"23:59:59:999:999:999",24*_1HOUR,ABSOLUTE);

In this example the Timer will be signaled "Everyday" at 12:00:00PM

Example2

use Win32::ISync;
my($TimerObj)= new Win32::ISync::Timer || die "Could not instanciate..\n";

if (!$TimerObj->Open(TIMER_ALL_ACCESS,INHERITED,"//TIMER/timer1"))
{print "\n Please hit <Enter> to start this demo...";

<STDIN>;

$TimerObj->Create(AUTORESET,"//TIMER/timer1");
#$TimerObj->LastError;
print "\nTimer object created...\n";
print "Now start a second instance of this script and press <Enter>... :";

<STDIN>;

$TimerObj->Set(CURRENT_DATE,"0:0:0:100:0:0",_1SEC,RELATIVE);
print "Press <Enter> to stop and close the Timer object... : ";

<STDIN>;

$TimerObj->Cancel;
$TimerObj->Close;
print "Timer object closed!\n";
} else{

print "\nTimer object opened,and now waiting for the signals...\n";

my($i)=10;

while($i--)
{$TimerObj->Wait(INFINITE);
print $i."\n";}
$TimerObj->Close;}

undef $TimerObj;

---

Index

Open($ct_Type_Access,$ct_Inherit,$Name)

Open Opens an existing named "waitable" timer object..

$ct_Type_Access: Specifies the requested access to the timer object,This parameter can be any combination of the following:

TIMER_ALL_ACCESS specifies all possible access rights for the timer object.
TIMER_MODIFY_STATE enables use of the timer handle in the Set() and Cancel() methods to modify the timer's state.
SYNCHRONIZE enables use of the timer handle in any of the wait functions to wait for the timer's state to be signaled.

$ct_Inherit: Specifies whether the returned handle is inheritable. If INHERITED, a process created by the CreateProcess function can inherit the handle;if it's NONINHERITED, the handle cannot be inherited.

$Name: Specifies the name of the timer object.

If Open()fails, the return value will be undef .To get extended error information, call LastError() method.

Example:

use Win32::ISync;
my($TimerObj)= new Win32::ISync::Timer;
$TimerObj->Open(TIMER_ALL_ACCESS,INHERITED,"//TIMER/Perl");

---

Index

Cancel()

Cancel Sets the specified "waitable" timer to the inactive state.

Remarks:

The Cancel() method does not change the signaled state of the timer. It stops the timer before it can be set to the signaled state. Therefore, threads performing a wait operation on the timer remain waiting until they time out or the timer is reactivated and its state is set to signaled.To reactivate the timer, call the Set() Timer method.

If the Cancel()fails, the return value will be undef .To get extended error information, call LastError() method.

---

Semaphore Class

Index

Create($InitialCount,$MaxCount,$Name)

Create() creates a "waitable" semaphore object.

$InitialCount specifies an initial count for the semaphore object. This value must be greater than or equal to zero and less than or equal to $MaxCount. The state of a semaphore is signaled when its count is greater than zero and nonsignaled when it is zero. The count is decreased by one whenever a wait function releases a thread that was waiting for the semaphore. The count is increased by a specified amount by calling the Release() method.

$MaxCount specifies the maximum count for the semaphore object. This value must be greater than zero.

$Name specifies the name of the semaphore object.

If the Create()fails, the return value will be undef .To get extended error information, call LastError().

Example1:

use Win32::ISync;
my($SemObj)= new Win32::ISync::Semaphore;
$SemObj->Create(0,1,"//SEMAPHORE/Perl");

Example2:

use Win32::ISync;

my($SemObj)=new Win32::ISync::Semaphore || die "Could not instanciate..\n";

if (!$SemObj->Open(SEMAPHORE_ALL_ACCESS,INHERITED,"//SEMAPHORE/semaphore1"))

{print "\n Please hit <Enter> to start this demo...";

<STDIN>;

$SemObj->Create(0,1,"//SEMAPHORE/semaphore1");
print "\nSemaphore object created...\n";
print "Now start a second instance of this script and press <Enter>.. :";

<STDIN>;

$SemObj->Release(1);
print "The last count of the semaphore is: $SemObj->{LastCount}\n";
print "Semaphore released...\n";
$SemObj->Close;
print "Semaphore object closed!\n";

} else {

print "\nSemaphore object opened, and now waiting for the signal...\n";

if($SemObj->Wait(INFINITE))

{print "Finally owning the mutex object!\n";
$SemObj->Release(1);
print "Semaphore released...\n";
$SemObj->Close;
print "Semaphore object closed!\n";}

else { print "Too lazy to wait!\n"; }

}

undef $SemObj;

---

Index

Open($ct_Type_Access,$ct_Inherit,$Name)

Open Opens an existing named semaphore object..

$ct_Type_Access: Specifies the requested access to the semaphore object,This parameter can be any combination of the following:

SEMAPHORE_ALL_ACCESS: Specifies all possible access rights for the semaphore object.
SEMAPHORE_MODIFY_STATE: Enables use of the semaphore handle in the Release() method to modify the semaphore's count.
SYNCHRONIZE Windows NT only: Enables use of the semaphore handle in any of the wait functions to wait for the semaphore's state to be signaled.

$ct_Inherit: Specifies whether the returned handle is inheritable. If INHERITED, a process created by the CreateProcess function can inherit the handle;if it's NONINHERITED, the handle cannot be inherited.

$Name: Specifies the name of the semaphore object.

If the Open()fails, the return value will be undef .To get extended error information, call the LastError() method.

Example:

use Win32::ISync;
my($SemObj)= new Win32::ISync::Semaphore; $SemObj->Open(SEMAPHORE_ALL_ACCESS,INHERITED,"//SEMAPHORE/Perl");

---

Index

Release($Count)

Release Increases the count of the specified semaphore object by a specified amount.

$Count: Specifies the amount by which the semaphore object's current count is to be increased. The value must be greater than zero. If the specified amount would cause the semaphore's count to exceed the maximum count that was specified when the semaphore was created, the count is not changed and the function returns FALSE.

If Release()fails, the return value will be undef .To get extended error information, call LastError().

Example:

use Win32::ISync;
my($SemObj)= new Win32::ISync::Semaphore;
$SemObj->Create(0,1,"//SEMAPHORE/semaphore1");
$SemObj->Release(1);

---

Mutex Class

Index

Create($ct_InitialOwner,$Name)

Create Creates a "waitable" Mutex object.

$ct_InitialOwner: Specifies the initial owner of the mutex object. If it is OWNED, the calling thread requests immediate ownership of the mutex object. if it is NOTOWNED, the mutex is not owned.

$Name: Specifies the name of the Mutex object.

If Create()fails, the return value will be undef .To get extended error information, call LastError().

Example1:

use Win32::ISync;
my($MutexObj)= new Win32::ISync::Mutex;
$MutexObj->Create(OWNED,"//MUTEX/Perl");

Example2:

use Win32::ISync;

my($MutexObj)=new Win32::ISync::Mutex || die "Could not instanciate..\n";

if (!$MutexObj->Open(MUTEX_ALL_ACCESS,INHERITED,"//MUTEX/mutex1"))

{print "\n Please hit <Enter> to start this demo...";

<STDIN>;

$MutexObj->Create(OWNED,"//MUTEX/mutex1");
print "\nMutex object created...\n";
print "Now start a second instance of this script and press <Enter>.. :";

<STDIN>;

$MutexObj->Release;
print "Mutex released...\n";
$MutexObj->Close;
print "Mutex object closed!\n";
}else {

print "\nMutex object opened,and now waiting for the signal...\n";

if($MutexObj->Wait(INFINITE))
{
print "Finally owning the mutex object!\n";
$MutexObj->Release;
print "Mutex released...\n";

#$MutexObj->LastError;

$MutexObj->Close;
print "Mutex object closed!\n";

} else { print "Too lazzy to wait!\n"; }

}

undef $MutexObj;

---

Index

.Open($ct_Type_Access,$ct_Inherit,$Name)

Open() Opens an existing named Mutex object..

$ct_Type_Access: Specifies the requested access to the Mutex object,This parameter can be any combination of the following:

MUTEX_ALL_ACCESS specifies all possible access rights for the semaphore object.
SYNCHRONIZE Windows NT only: Enables use of the Mutex handle in any of the wait functions to wait for the semaphore's state to be signaled.

$ct_Inherit specifies whether the returned handle is inheritable. If INHERITED, a process created by the CreateProcess function can inherit the handle;if it's NONINHERITED, the handle cannot be inherited.

$Name specifies the name of the Mutex object.

If Open()fails, the return value will be undef .To get extended error information, call LastError().

Example:

use Win32::ISync;
my($MutexObj)= new Win32::ISync::Mutex;
$MutexObj->Open(MUTEX_ALL_ACCESS,INHERITED,"//MUTEX/Perl");

---

Index

Release()

Release Releases ownership of the specified mutex object.

If Release()fails, the return value will be undef .To get extended error information, call LastError().

Example:

use Win32::ISync;
my($MutexObj)= new Win32::ISync::Mutex;
$MutexObj->Create(OWNED,"//MUTEX/Perl");
$MutexObj->Release();

---

Event Class

Index

Create($ct_Type,$InitialState,$Name)

Create Creates a "waitable" event object.

$ct_Type: Specifies whether a manual-reset or auto-reset event object is created. If MANUALRESET, then you must use the Reset() method to manually reset the state to nonsignaled. If AUTORESET, Windows automatically resets the state to nonsignaled after a single waiting thread has been released.

$InitialSate Specifies the initial state of the event object. If it's SIGNALED, the initial state is signaled; if NONSIGNALED, it is nonsignaled.

$Name: Specifies the name of the mutex object.

If Create()fails, the return value will be undef .To get extended error information, call LastError().

Example1:

use Win32::ISync;
my($EventObj)= new Win32::ISync::Event;
$EventObj->Create(NONSIGNALED,AUTORESET,"//EVENT/Perl");

Example2:

use Win32::ISync;

my($EventObj)=new Win32::ISync::Event || die "Could not instanciate..\n";;;

if (!$EventObj->Open(EVENT_ALL_ACCESS,INHERITED,"//EVENT/event1"))

{print "\n Please hit <Enter> to start this demo...";

<STDIN>;

$EventObj->Create(AUTORESET,NONSIGNALED,"//EVENT/event1");
print "\nEvent object created...\n";
print "Now start a second instance of this script and press <Enter>.. :";

<STDIN>;

$EventObj->Pulse;
print "Event object Pulsed...\n";
$EventObj->Close;

} else {

print "\nEvent object opened,and now waiting for the signal...\n";

if($EventObj->Wait(INFINITE))

{print "Finally owning the event object!\n";
$EventObj->Close;

} else {print "Too lazy to wait!\n";}

}

undef $EventObj;

---

Index

Open($ct_Type_Access,$ct_Inherit,$Name)

Open Opens an existing named "waitable" timer object..

$ct_Type_Access: Specifies the requested access to the event object,This parameter can be any combination of the following:

EVENT_ALL_ACCESS: specifies all possible access rights for the event object.
EVENT_MODIFY_STATE: enables use of the event handle in the Set() and Reset() methods to modify the event's state.
SYNCHRONIZE: enables use of the event handle in any of the wait functions to wait for the event's state to be signaled.

$ct_Inherit: Specifies whether the returned handle is inheritable. If INHERITED, a process created by the CreateProcess function can inherit the handle;if it's NONINHERITED, the handle cannot be inherited.

$Name: Specifies the name of the event object.

If Open()fails, the return value will be undef .To get extended error information, call LastError().

Example:

use Win32::ISync;
my($EventObj)= new Win32::ISync::Event;
$EventObj->Open(EVENT_ALL_ACCESS,INHERITED,"//EVENT/Perl");

---

Index

Reset()

Reset Sets the state of the specified event object to nonsignaled.

Set()

Set Sets the state of the specified event object to signaled.