Semaphore Class Reference

#include <Semaphore.h>

Inheritance diagram for Semaphore:

Collaboration diagram for Semaphore:

Classes
class	SemaphoreEvent

Public Types
enum	SemaphoreError { TimedOut , Interrupted , NoError }

Public Member Functions
	Semaphore (size_t nInitialValue, bool canInterrupt=true)
virtual	~Semaphore ()
MUST_USE_RESULT bool	acquireWithError (size_t n, size_t timeoutSecs, size_t timeoutUsecs, SemaphoreError &error)
MUST_USE_RESULT bool	acquireForCompletion (size_t n=1, size_t timeoutSecs=0, size_t timeoutUsecs=0)
bool	acquire (size_t n=1, size_t timeoutSecs=0, size_t timeoutUsecs=0)
bool	tryAcquire (size_t n=1)
MUST_USE_RESULT size_t	drainAvailable ()
void	release (size_t n=1)
ssize_t	getValue ()
const void *	getDebugMutexOwner () const

Protected Member Functions
void	initialiseMutex (bool locked)
void	destroyMutex ()
bool	mutexOwnedByCurrentThread () const

Private Types
typedef Result< bool, SemaphoreError >	SemaphoreResult

Private Member Functions
MUST_USE_RESULT SemaphoreResult	acquireWithResult (size_t n=1, size_t timeoutSecs=0, size_t timeoutUsecs=0, bool deferTerminal=false)
	Semaphore (const Semaphore &)
void	operator= (const Semaphore &)

Private Attributes
size_t	magic
Atomic< ssize_t >	m_Counter
WaitQueue	m_Waiters
bool	m_bCanInterrupt

Detailed Description

A counting semaphore.

Definition at line 36 of file Semaphore.h.

Member Typedef Documentation

SemaphoreResult

typedef Result<bool, SemaphoreError> Semaphore::SemaphoreResult

private

Definition at line 123 of file Semaphore.h.

Member Enumeration Documentation

SemaphoreError

enum Semaphore::SemaphoreError

Definition at line 38 of file Semaphore.h.

Constructor & Destructor Documentation

Semaphore() [1/2]

Semaphore::Semaphore	(	size_t	nInitialValue,
		bool	canInterrupt = true
	)

Constructor

Parameters

nInitialValue	The initial value of the semaphore.
canInterrupt	If false, acquire() retries after interrupt rather than returning a failure status.

Definition at line 151 of file Semaphore.cc.

~Semaphore()

Semaphore::~Semaphore ( )

virtual

Destructor

Definition at line 156 of file Semaphore.cc.

Semaphore() [2/2]

Semaphore::Semaphore ( const Semaphore &  )

private

Private copy constructor

Note

NOT implemented.

Member Function Documentation

acquire()

bool Semaphore::acquire	(	size_t	n = 1,
		size_t	timeoutSecs = 0,
		size_t	timeoutUsecs = 0
	)

Convenience wrapper for acquire().

Definition at line 352 of file Semaphore.cc.

Referenced by acquireForCompletion(), PerProcessorScheduler::addThread(), PerProcessorScheduler::addThread(), NetworkStack::deRegisterDevice(), ProducerConsumer::destroy(), LockedFile::lock(), LockedFile::LockedFile(), InputManager::mainThread(), EventFd::readValue(), Directory::reserveDirectoryEntry(), GraphicsService::serve(), sys_mutex_lock(), Pipe::waitForReader(), EventFd::writeValue(), and Pipe::~Pipe().

Here is the caller graph for this function:

acquireForCompletion()

bool Semaphore::acquireForCompletion	(	size_t	n = 1,
		size_t	timeoutSecs = 0,
		size_t	timeoutUsecs = 0
	)

Acquires a semaphore used as an internal completion barrier.

Signal events are delivered while blocked, but do not complete the barrier. The signal interruption marker is restored after the semaphore is acquired (or the original timeout expires), allowing an outer syscall boundary to report EINTR without abandoning storage still owned by the asynchronous operation.

Definition at line 369 of file Semaphore.cc.

References acquire(), EMIT_IF, ProcessorBase::guardDeviceHardIrqOperation(), ProcessorBase::information(), and tryAcquire().

Referenced by AtaDisk::doRead(), UsbHub::doSync(), Nic3C90x::send(), sys_arch_sem_wait(), and AtaDisk::writePageBuffer().

Here is the caller graph for this function:

acquireWithError()

bool Semaphore::acquireWithError	(	size_t	n,
		size_t	timeoutSecs,
		size_t	timeoutUsecs,
		SemaphoreError &	error
	)

Acquires n items and reports the exact failure in error.

Definition at line 357 of file Semaphore.cc.

Referenced by UsbHub::doSync(), and EpollInstance::wait().

Here is the caller graph for this function:

acquireWithResult()

Semaphore::SemaphoreResult Semaphore::acquireWithResult ( size_t  n = 1, size_t  timeoutSecs = 0, size_t  timeoutUsecs = 0, bool  deferTerminal = false  )

private

Definition at line 160 of file Semaphore.cc.

destroyMutex()

void Semaphore::destroyMutex ( )

protected

Definition at line 616 of file Semaphore.cc.

drainAvailable()

size_t Semaphore::drainAvailable

(

)

Atomically removes and returns every currently available item.

Definition at line 528 of file Semaphore.cc.

Referenced by Nic3C90x::send().

Here is the caller graph for this function:

getDebugMutexOwner()

const void * Semaphore::getDebugMutexOwner

(

)

const

Returns the owning thread address when this is a locked Mutex.

This is a read-only, best-effort debugger snapshot. A plain Semaphore or unlocked Mutex returns nullptr.

Definition at line 602 of file Semaphore.cc.

getValue()

ssize_t Semaphore::getValue

(

)

Gets the current value of the semaphore

Definition at line 598 of file Semaphore.cc.

initialiseMutex()

void Semaphore::initialiseMutex ( bool  locked )

protected

Reuses this semaphore's storage for Mutex ownership state. These hooks keep Mutex layout-compatible with its historical empty subclass while ensuring calls through either the Mutex or Semaphore interface enforce mutex ownership.

Definition at line 611 of file Semaphore.cc.

Referenced by Mutex::Mutex().

Here is the caller graph for this function:

mutexOwnedByCurrentThread()

bool Semaphore::mutexOwnedByCurrentThread ( ) const

protected

Definition at line 624 of file Semaphore.cc.

operator=()

void Semaphore::operator= ( const Semaphore &  )

private

Private operator=

Note

NOT implemented.

release()

void Semaphore::release

(

size_t

n = 1

)

Releases n items from the semaphore.

Parameters

n	The number of semaphore items to release. Must be non-zero.

Definition at line 546 of file Semaphore.cc.

References EMIT_IF, ProcessorBase::guardDeviceHardIrqOperation(), and WaitQueue::wakeAllIfWaiting().

Referenced by PosixSubsystem::acquireFileDescriptor(), PosixSubsystem::acquireNextFileDescriptor(), PosixSubsystem::addFileDescriptor(), PerProcessorScheduler::addThread(), PerProcessorScheduler::addThread(), PosixSubsystem::allocateFd(), PosixSubsystem::closeFileDescriptor(), MemoryMappedFile::compact(), PosixSubsystem::copyDescriptors(), NetworkStack::deRegisterDevice(), PosixSubsystem::descriptorMatchesOpenDescription(), ProducerConsumer::destroy(), PosixSubsystem::duplicateFileDescriptor(), Uhci::enqueueCompletedTransfer(), PosixSubsystem::freeFd(), PosixSubsystem::freeMultipleFds(), PosixSubsystem::getFd(), TextIO::initialise(), PosixSubsystem::installFileDescriptor(), Nic3C90x::irq(), CdiIrqHandler::irq(), AtaDisk::irqReceived(), RingBuffer< T, preallocatedSize >::monitor(), Buffer< T, allowShortOperation >::notifyMonitorsLocked(), InputManager::putNotification(), File::readIntoCache(), EventFd::readValue(), PosixSubsystem::release(), Directory::reserveDirectoryEntry(), GraphicsService::serve(), VmwareGraphics::setScreenMode(), InputManager::shutdown(), UsbHub::syncCallback(), sys_mutex_unlock(), sys_sem_signal(), MemoryPool::trim(), Ext2File::tryBeginMappingRelease(), LockedFile::unlock(), Pipe::waitForReader(), EventFd::writeValue(), and Pipe::~Pipe().

Here is the caller graph for this function:

tryAcquire()

bool Semaphore::tryAcquire

(

size_t

n = 1

)

Attempts to acquire n items from the semaphore. This will not block.

Parameters

n	The number of semaphore items required. Must be non-zero.

Returns

True if acquire succeeded, false otherwise.

Definition at line 481 of file Semaphore.cc.

References EMIT_IF.

Referenced by acquireForCompletion(), MemoryMappedFile::compact(), TextIO::initialise(), LockedFile::lock(), GraphicsService::serve(), VmwareGraphics::setScreenMode(), MemoryPool::trim(), File::tryBeginMappingRelease(), Ext2File::tryBeginMappingRelease(), and EpollInstance::wait().

Here is the caller graph for this function:

Member Data Documentation

m_bCanInterrupt

bool Semaphore::m_bCanInterrupt

private

Definition at line 151 of file Semaphore.h.

m_Counter

Atomic<ssize_t> Semaphore::m_Counter

private

Definition at line 149 of file Semaphore.h.

m_Waiters

WaitQueue Semaphore::m_Waiters

private

Definition at line 150 of file Semaphore.h.

magic

size_t Semaphore::magic

private

Definition at line 147 of file Semaphore.h.

---

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

• Semaphore.h
• Semaphore.cc