A handle to a semaphore. More...

#include <e32cmn.h>

Inheritance diagram for RSemaphore:

Public Member Functions
TInt	Open (const TFindSemaphore &aFind, TOwnerType aType=EOwnerProcess)
	Opens a handle to the global semaphore found using a TFindSemaphore object.

IMPORT_C TInt	CreateLocal (TInt aCount, TOwnerType aType=EOwnerProcess)
	Creates a semaphore, setting its initial count, and opens this handle to the semaphore.

IMPORT_C TInt	CreateGlobal (const TDesC &aName, TInt aCount, TOwnerType aType=EOwnerProcess)
	Creates a global semaphore, setting its initial count, and opens this handle to the semaphore.

IMPORT_C TInt	OpenGlobal (const TDesC &aName, TOwnerType aType=EOwnerProcess)
	Opens a handle to a global semaphore.

IMPORT_C TInt	Open (RMessagePtr2 aMessage, TInt aParam, TOwnerType aType=EOwnerProcess)
	Opens a handle to a semaphore using a handle number sent by a client to a server.

IMPORT_C TInt	Open (TInt aArgumentIndex, TOwnerType aType=EOwnerProcess)
	Opens a handle to a semaphore using a handle number passed as an environment data item to the child process during the creation of that child process.

IMPORT_C void	Wait ()
	Waits for a signal on the semaphore.

IMPORT_C TInt	Wait (TInt aTimeout)
	Waits for a signal on the semaphore, or a timeout.

IMPORT_C TInt	Poll ()

IMPORT_C void	Signal ()
	Signals the semaphore once.

IMPORT_C void	Signal (TInt aCount)
	Signals the semaphore one or more times.

Public Member Functions inherited from RHandleBase
	RHandleBase ()
	Default constructor.

TInt	Handle () const
	Retrieves the handle-number of the object associated with this handle.

void	SetHandle (TInt aHandle)
	Sets the handle-number of this handle to the specified value.

TInt	SetReturnedHandle (TInt aHandleOrError)
	Sets the handle-number of this handle to the specified value.

IMPORT_C void	Close ()
	Closes the handle.

IMPORT_C TName	Name () const
	Gets the name of the handle.

IMPORT_C TFullName	FullName () const
	Gets the full name of the handle.

IMPORT_C void	FullName (TDes &aName) const
	Gets the full name of the handle.

IMPORT_C void	SetHandleNC (TInt aHandle)
	Sets the handle-number of this handle to the specified value, and marks it as not closable.

IMPORT_C TInt	Duplicate (const RThread &aSrc, TOwnerType aType=EOwnerProcess)
	Creates a valid handle to the kernel object for which the specified thread already has a handle.

IMPORT_C void	HandleInfo (THandleInfo *anInfo)
	Gets information about the handle.

IMPORT_C TUint	Attributes () const

IMPORT_C TInt	BTraceId () const
	Returns a unique object identifier for use with BTrace.

IMPORT_C void	NotifyDestruction (TRequestStatus &aStatus)
	Internal technology API.

Additional Inherited Members
Public Types inherited from RHandleBase
enum	TAttributes { EReadAccess =0x1 , EWriteAccess =0x2 , EDirectReadAccess =0x4 , EDirectWriteAccess =0x8 }
	Read/Write attributes for the handle. More...

Static Public Member Functions inherited from RHandleBase
static void	DoExtendedClose ()

Protected Member Functions inherited from RHandleBase
	RHandleBase (TInt aHandle)
	Copy constructor.

IMPORT_C TInt	Open (const TFindHandleBase &aHandle, TOwnerType aType)
	Opens a handle to a kernel side object found using a find-handle object.

TInt	OpenByName (const TDesC &aName, TOwnerType aOwnerType, TInt aObjectType)
	Implementation for RXxxxx::Open/OpenGlocbal(const TDesC &aName,,TOwnerType aType) functions.

Static Protected Member Functions inherited from RHandleBase
static TInt	SetReturnedHandle (TInt aHandleOrError, RHandleBase &aHandle)

Protected Attributes inherited from RHandleBase
TInt	iHandle

Detailed Description

A handle to a semaphore.

The semaphore itself is a Kernel side object.

As with all handles, they should be closed after use. RHandleBase provides the necessary Close() function, which should be called when the handle is no longer required.

See also: RHandleBase::Close

API status: Published to all clients. Released API.

Definition at line 2635 of file e32cmn.h.

Member Function Documentation

◆ CreateGlobal()

IMPORT_C TInt RSemaphore::CreateGlobal	(	const TDesC &	aName,
		TInt	aCount,
		TOwnerType	aType = `EOwnerProcess`
	)

Creates a global semaphore, setting its initial count, and opens this handle to the semaphore.

The kernel side object representing the semaphore is given the name contained in the specified descriptor, which makes it global. This means that any thread in any process can search for the semaphore, using TFindSemaphore, and open a handle to it. If the specified name is empty the kernel side object representing the semaphore is unnamed and so cannot be opened by name. It can however be passed to another process as a process parameter or via IPC.

By default, any thread in the process can use this instance of RSemaphore to access the semaphore. However, specifying EOwnerThread as the third parameter to this function, means that only the creating thread can use this instance of RSemaphore to access the semaphore; any other thread in this process that wants to access the semaphore must either duplicate this handle or use OpenGlobal().

Parameters

aName	A reference to the descriptor containing the name to be assigned to this global semaphore.
aCount	The initial value of the semaphore count.
aType	An enumeration whose enumerators define the ownership of this semaphore handle. If not explicitly specified, EOwnerProcess is taken as default.

Panic condition: USER 105 if aCount is negative.

(generated from Symbian Developer Library)

◆ CreateLocal()

IMPORT_C TInt RSemaphore::CreateLocal	(	TInt	aCount,
		TOwnerType	aType = `EOwnerProcess`
	)

Creates a semaphore, setting its initial count, and opens this handle to the semaphore.

The kernel side object representing the semaphore is unnamed. This means that it is not possible to search for the semaphore, which makes it local to the current process.

By default, any thread in the process can use this instance of RSemaphore to access the semaphore. However, specifying EOwnerThread as the second parameter to this function, means that only the creating thread can use this instance of RSemaphore to access the semaphore; any other thread in this process that wants to access the semaphore must duplicate this handle.

Parameters

aCount	The initial value of the semaphore count.
aType	An enumeration whose enumerators define the ownership of this semaphore handle. If not explicitly specified, EOwnerProcess is taken as default.

Panic condition: USER 105 if aCount is negative.

(generated from Symbian Developer Library)

◆ Open() [1/3]

TInt RSemaphore::Open	(	const TFindSemaphore &	aFind,
		TOwnerType	aType = `EOwnerProcess`
	)

inline

Opens a handle to the global semaphore found using a TFindSemaphore object.

A TFindSemaphore object is used to find all global semaphores whose full names match a specified pattern.

By default, any thread in the process can use this instance of RSemaphore to access the semaphore. However, specifying EOwnerThread as the second parameter to this function, means that only the opening thread can use this instance of RSemaphore to access the semaphore; any other thread in this process that wants to access the semaphore must either duplicate the handle or use OpenGlobal() again.

Parameters

aFind	A reference to the TFindSemaphore object used to find the semaphore.
aType	An enumeration whose enumerators define the ownership of this semaphore handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Open() [2/3]

IMPORT_C TInt RSemaphore::Open	(	RMessagePtr2	aMessage,
		TInt	aParam,
		TOwnerType	aType = `EOwnerProcess`
	)

Opens a handle to a semaphore using a handle number sent by a client to a server.

This function is called by the server.

Parameters

aMessage	The message pointer.
aParam	An index specifying which of the four message arguments contains the handle number.
aType	An enumeration whose enumerators define the ownership of this semaphore handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Open() [3/3]

IMPORT_C TInt RSemaphore::Open	(	TInt	aArgumentIndex,
		TOwnerType	aType = `EOwnerProcess`
	)

Opens a handle to a semaphore using a handle number passed as an environment data item to the child process during the creation of that child process.

Note that this function can only be called successfully once.

RProcess::SetParameter()

Parameters

aArgumentIndex	An index that identifies the slot in the process environment data that contains the handle number. This is a value relative to zero, i.e. 0 is the first item/slot. This can range from 0 to 15.
aType	An enumeration whose enumerators define the ownership of this semaphore handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ OpenGlobal()

IMPORT_C TInt RSemaphore::OpenGlobal	(	const TDesC &	aName,
		TOwnerType	aType = `EOwnerProcess`
	)

Opens a handle to a global semaphore.

Global semaphores are identified by name.

By default, any thread in the process can use this instance of RSemaphore to access the semaphore. However, specifying EOwnerThread as the second parameter to this function, means that only the opening thread can use this instance of RSemaphore to access the semaphore; any other thread in this process that wants to access the semaphore must either duplicate the handle or use OpenGlobal() again.

RHandleBase::Duplicate()

Parameters

aName	A reference to the descriptor containing the name of the global semaphore to be opened.
aType	An enumeration whose enumerators define the ownership of this semaphore handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Poll()

IMPORT_C TInt RSemaphore::Poll ( )

◆ Signal() [1/2]

IMPORT_C void RSemaphore::Signal ( )

Signals the semaphore once.

The function increments the semaphore count by one. If the count was negative before being incremented, the highest priority thread waiting on the semaphore's queue of threads is removed from that queue and, provided that it is not suspended for any other reason, is marked as ready to run.

(generated from Symbian Developer Library)

◆ Signal() [2/2]

IMPORT_C void RSemaphore::Signal ( TInt aCount )

Signals the semaphore one or more times.

The function increments the semaphore count. If the count was negative before being incremented, the highest priority thread waiting on the semaphore's queue of threads is removed from that queue and, provided that it is not suspended for any other reason, is marked as ready to run.

Parameters

aCount The number of times the semaphore is to be signalled.

(generated from Symbian Developer Library)

◆ Wait() [1/2]

IMPORT_C void RSemaphore::Wait ( )

Waits for a signal on the semaphore.

The function decrements the semaphore count by one and returns immediately if it is zero or positive.

If the semaphore count is negative after being decremented, the calling thread is added to a queue of threads maintained by this semaphore.

The thread waits until the semaphore is signalled. More than one thread can be waiting on a particular semaphore at a time. When there are multiple threads waiting on a semaphore, they are released in priority order.

If the semaphore is deleted, all threads waiting on that semaphore are released.

(generated from Symbian Developer Library)

◆ Wait() [2/2]

IMPORT_C TInt RSemaphore::Wait ( TInt aTimeout )

Waits for a signal on the semaphore, or a timeout.

Parameters

aTimeout The timeout value in micoseconds

(generated from Symbian Developer Library)

The documentation for this class was generated from the following files:

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ CreateGlobal()

◆ CreateLocal()

◆ Open() [1/3]

◆ Open() [2/3]

◆ Open() [3/3]

◆ OpenGlobal()

◆ Poll()

◆ Signal() [1/2]

◆ Signal() [2/2]

◆ Wait() [1/2]

◆ Wait() [2/2]