|
CoreLinux++
Functional Requirement Document
Revision $Revision: 1.2 $
Last
Modified : Tuesday, February 29, 2000
Title : Semaphores
1. Introduction
A Semaphore is a protocol that processes and/or threads agree to
follow for the purpose of controlled access to a resource. The
resource can be anything that the developer considers to need access
controls on such as memory, hardware, methods, computer instructions,
and so on.
Callers can elect to avoid being put into a blocked state and
return immediately without control to the resource. Callers may also
request that they are put into a blocked state for a specified amount
of time. If, at the end of the specified time, the request has not
been satisfied, it is returned with a Timeout indicator.
The owner or creator of the semaphore can elect to enforce balking
behavior on a Semaphore. When so designated, the Semaphore can turn
back any request until some condition in their solution space is met
regardless of the callers blocking options. If a caller access
attempt is balked, is it returned with a Balked indicator.
1.1 Deliverables Overview
Used to serialized access to a resource (one to one)
When used to prevent concurrent access to a resource, the caller
must first obtain control of the associated Semaphore. When a caller
has control of the Semaphore, the resource(s) that are associated
with the Semaphore are considered locked and accessible by the
caller. When the caller has completed access of the resource it
relinquishes control and the resource is now considered unlocked.
Attempts may be made to access the resource by other threads of
execution or from separate processes. These callers are queued and
the requester is put into a blocked state. In this state the caller
waits until the resource is unlocked. If multiple requests are
blocking for the same control, the determination of which caller
gains access next is, from a applications perspective, arbitrary.
When balking mode is enabled callers will be turned away as long
as the Semaphore is locked.
Used to provide concurrent finite access (one to many)
When used in this fashion, a Semaphore can be used as an access
count controller. The Semaphore is created, as determined by the
solution domain, with the maximum number of concurrent active callers
allowed. As long as the caller count does not reach the maximum, the
arrival will be granted immediate access. When the maximum has been
reached, arriving callers are blocked.
When balking mode is enabled callers will be turned away until the
count reduces to less than maximum.
Used to block callers until an event occurs (many to one)
When used in this fashion, a single Semaphore is used to let
callers block until some event occurs. Unlike the serialized access,
where one caller at a time is released to gain access to a resource,
when the designated event occurs all blocked callers are released at
once.
The creator of this type of Semaphore can designate the maximum
number of listeners that can wait on a single Semaphore event. When
used in this manner, balking mode is automatically enabled.
When balking mode is enabled callers will be turned away until the
number of listeners on the event drops below maximum.
Semaphore Groups
A Semaphore group is an extension to the Linux semaphore set. This
provides a way to logically group semaphores. For example, it may be
useful in a solution domain to group One-To-One semaphores
differently from Many-to-One semaphores.
A Semaphore group acts as a semaphore factory, creating and
destroying semaphores for the user.
2. Functional Requirements
Semaphore Group Requirements
All Semaphore Groups will support named creation.
All Semaphore Groups will support maximum group count
creation. This identifies the number of maximum semaphores in the
group.
All Semaphore Groups will support a segregation by type
(One-to-One, One-to-Many, and Many-to-One).
All Semaphore Groups will support instrumentation.
All Semaphore Groups shall be responsible for Semaphore
"creates".
All Semaphore Groups shall be responsible for Semaphore
"destroys".
CoreLinux++ will support a default, heterogeneous, Semaphore
Group. Name TBD,
maximum semaphore count TBD.
The CoreLinux++ default Semaphore Group shall chain new group
instances for user "get" operations.
General Semaphore Requirements
There shall be no restriction on the type of the Semaphore
that can be created other than system dependent resources. In this
event, an exception will be thrown indicating, if possible, why the
Semaphore could not be created.
The default mode for all Semaphore will be non-Balking.
All Semaphores will support instrumentation.
All Semaphores will support access by only the process that
creates it.
All Semaphores will support access by the process that
creates it, and any children that the process spawns.
All Semaphores will support access by any process.
All Semaphores will support read only operations for each of
the above access modes.
All Semaphores will support read/write operations for each of
the above access modes.
All Semaphores will support a recursion disposition.
All Semaphores will support a lock semantic in that the
caller will wait until the lock is obtained.
All Semaphores will support the lock semantic with no-wait
option so that the caller will return immediately if the lock can
not be immediately obtained.
All Semaphores will support the lock semantic with timeout
option so that the caller can indicate a maximum amount of time
before giving up trying to obtain the lock.
One-to-One Semaphore Requirements
One-to-One Semaphores will support a create and automatically
lock capability.
One-to-One Semaphores will support a create and no-lock
capability.
One-to-Many Semaphore Requirements
One-to-Many Semaphores will support a create with a maximum
resource count.
One-to-Many Semaphores will support a create and
automatically lock capability which means no resources are
available.
One-to-Many Semaphores will support a create and no-lock
capability which means all (maximum) resources are available.
One-to-Many Semaphores will support increasing the maximum
count.
Many-to-One Semaphore Requirements
Many-to-One Semaphores will support a create with a maximum
"listener" count
Many-to-One Semaphores will automatically lock upon creation.
There is not option to create it unlocked.
Many-to-One Semaphores will support increasing the maximum
"listener" count if balking mode enabled.
2.1 User Interface Specifications
NA
2.2 Product Services
NA
2.3 External Interfaces and Database Requirements
NA
2.4 Error Handling
Invarient violations will be relayed to the user through a
SemaphoreException type. Type will indicate the violation.
All operating system errors related to the underlying
semaphore implementation will be relayed to the user through a
return code of the method called when the error occurred.
Balking conditions will be relayed to the user through a
return code of the method called when the error occurred.
Timeout conditions will be relayed to the user through a
return code of the method called when the error occurred.
2.5 Foreseeable Functional Changes and Enhancements
There has been a request that a Many-to-One Semaphore support a
callback metaphor where the "listener" is notified via a
specified method address.
3. Non-Functional Requirements
3.1 Performance Requirements
Basic CoreLinux++ Semaphores (One-to-One, One-to-Many) add a thin
layer over the underlying operating system, therefore the cost for a
Semaphore object will be slightly higher. The Many-to-One Semaphore
type represents a degenerate case, because there is no underlying
operating support. The team will endeavor to implement with the
minimal amount of overhead to meet the functional requirements.
3.2 User Documentation and Other User Aids
Use Case, Analysis, Design, and Class Reference documentation.
3.3 Development Requirements
Standards: CoreLinux++ C++ Standards and
Guidelines
3.4 Foreseeable Non-Functional Changes
TBD
4. Remarks and Guidelines for Later Life Cycle Phases
TBD
5. Term Glossary
Copyright © 1999, 2000 by CoreLinux Consortium
This material may be distributed only subject to the terms and conditions set forth in the
Open Publication License
|
