|
hurd-java
Java bindings for Mach and Hurd
|
Opaque Mach port name. More...
Public Types | |
| enum | Right { SEND, RECEIVE, SEND_ONCE, PORT_SET, DEAD_NAME } |
| Port rights for MachPort#allocate. More... | |
Public Member Functions | |
| MachPort (int name) throws Unsafe | |
| Instanciate a new MachPort object for the given name. | |
| synchronized int | name () throws Unsafe |
| Acquire the port name associated with this object. | |
| synchronized void | releaseName () throws Unsafe |
| Release a reference acquired through name(). | |
| synchronized int | clear () throws Unsafe |
| Replace the port name encapsulated by this object with MACH_PORT_DEAD. | |
| synchronized void | deallocate () |
| Deallocate this port. | |
Static Public Member Functions | |
| static MachPort | allocateReplyPort () |
| Allocate a new reply port. | |
| static MachPort | allocate (Right right) |
| Allocate a new port name. | |
| static MachPort | allocate () |
| Allocate a new receive port right. | |
Static Public Attributes | |
| static final MachPort | NULL = null |
MachPort object for MACH_PORT_NULL. | |
| static final MachPort | DEAD |
MachPort object for MACH_PORT_DEAD. | |
Protected Member Functions | |
| void | finalize () |
Static Package Functions | |
| [static initializer] | |
Opaque Mach port name.
This class encapsulates mach_port_t values in a safe manner. Users of the org.gnu.mach package never manipulate port names directly. Instead, they refer to ports using MachPort objects.
MachPort objects generally behave the same way mach_port_t values do. They are created when incoming RPC messages are parsed. The equals() method can be used to determine whether two send right refer to the same object (XXX not implemented yet).
The encapsulated port name can be retreived by unsafe code using the name and clear methods.
To ensure the port name remains valid between the time it's acquired and the time it is actually used, name increments an external reference counter. Calls to clear and deallocate will block until the external reference is released using releaseName.
By contrast, clear replaces the encapsulated port name with MACH_PORT_DEAD and returns its previous value to the caller, which becomes responsible for the corresponding Mach user reference previously associated with the MachPort object.
One particular concern is how we should handle the special port names MACH_PORT_NULL and MACH_PORT_DEAD. The constants MachPort#NULL and MachPort#DEAD are provided as the safe equivalents. However we must consider the possibility that they could be mutated by clear or deallocate.
Since both of these methods replace the encapsulated port name with Mach.Port.DEAD, this is an issue only with MachPort#NULL. So far we specify that the user code should explicitely check for it and handle it consequently, and MachPort#NULL is defined to null. It is clumsy, though.
Alternatively we could check the encapsulated port name explicitely so that NULL stays NULL even when it's cleared. Another possibility would be to provide static wrappers for name, releaseName and clear which would handle the case of a null reference.
Note that to preserve safety, MachPort must be final, so using a subclass for special ports unfortunately is not an option.
Definition at line 55 of file MachPort.java.
Port rights for MachPort#allocate.
Definition at line 82 of file MachPort.java.
| org.gnu.mach.MachPort.MachPort | ( | int | name | ) | throws Unsafe |
Instanciate a new MachPort object for the given name.
This consumes one reference to name. The reference will be released when deallocate() is called, or when the new object is collected.
Definition at line 107 of file MachPort.java.
| org.gnu.mach.MachPort.[static initializer] | ( | ) | [static, package] |
| static MachPort org.gnu.mach.MachPort.allocate | ( | ) | [static] |
Allocate a new receive port right.
Definition at line 203 of file MachPort.java.
Allocate a new port name.
Definition at line 191 of file MachPort.java.
| static MachPort org.gnu.mach.MachPort.allocateReplyPort | ( | ) | [static] |
Allocate a new reply port.
Definition at line 179 of file MachPort.java.
| synchronized int org.gnu.mach.MachPort.clear | ( | ) | throws Unsafe |
Replace the port name encapsulated by this object with MACH_PORT_DEAD.
The previous port name is not deallocated, but is instead returned to the caller. It is the caller's responsability to ensure that the corresponding Mach-level port right reference does not leak.
If external references to the port name exist, the call will block until they have all been released.
Definition at line 148 of file MachPort.java.
| synchronized void org.gnu.mach.MachPort.deallocate | ( | ) |
Deallocate this port.
The encapsulated port name is replaced with MACH_PORT_DEAD. If external references to the port name exist, the call will block until they have all been released.
Definition at line 169 of file MachPort.java.
| void org.gnu.mach.MachPort.finalize | ( | ) | [protected] |
Definition at line 210 of file MachPort.java.
| synchronized int org.gnu.mach.MachPort.name | ( | ) | throws Unsafe |
Acquire the port name associated with this object.
This unsafe operation permits access to the port name encapsulated in this MachPort object. To prevent the name from being rendered invalid by deallocation after it has been obtained, calling this method will increment the external reference counter. Any deallocation request will block until releaseName() is called.
Definition at line 122 of file MachPort.java.
| synchronized void org.gnu.mach.MachPort.releaseName | ( | ) | throws Unsafe |
Release a reference acquired through name().
Definition at line 131 of file MachPort.java.
final MachPort org.gnu.mach.MachPort.DEAD [static] |
MachPort object for MACH_PORT_DEAD.
Definition at line 64 of file MachPort.java.
final MachPort org.gnu.mach.MachPort.NULL = null [static] |
MachPort object for MACH_PORT_NULL.
Definition at line 59 of file MachPort.java.
1.7.4
