Specifiction for Eric v2.0
By Gavin R. Brewer
25/07/01
int kPort::names( kTask* task,
Array<long> *names, int namesCnt,
Array<int> *types,int typesCnt);
Arguments:
task
The task whose port name space is queried.
names
The names of the ports and port sets in the task's port name space, in no particular order.
Returns the valid ports and port set names of the current task.
For each name it also returns what type of rights the task holds. 'names' and 'types' are arrays that are automatically allocated when message is received. The user may wish to remove them from the VM system when the data is no longer needed.
Returns:
ERIC_SUCCESS The call succeeded.
ERIC_INVALID_ARGUMENT task was invalid
int kPort::type( long task, int name, int type );
Arguments:
task The task whose port name space is queried
name The name being queried
type The type of the name
Description:
Returns information about the task's rights for a specific name in its port namespace.
Returns:
ERIC_SUCCESS The call succeeded
ERIC_INVALID_ARGUMENT 'task' was invalid or 'task' did not have any
rights named 'name'
int kPort::allocate( kTask* task, long& name );
Arguments:
task The task in which the new port is created
name The task's name for the new port
Description:
Causes a port to be created for the specified task; the resulting port's name is returned in 'name'.
The target task initially has all three access rights to the port. If the caller is not the task specified by 'task', then it does not have any rights to the port.
The new port is not a member of member of any port set.
Returns:
ERIC_SUCCESS The call succeeded
ERIC_INVALID_SUCCESS 'task' was invalid
ERIC_RESOURCE_SHORTAGE The kernel ran out of memory.
int kPort::status( kTask* task, long name,
int& enabled, int& num_msgs,
int& backlog, int& owner, int& receiver );
Arguments:
task The task owning the port right in question
name task's name for the port right.
enabled returns task's name for the port set which the named port belongs to, or PORT_NULL if it isnt in a set.
num_mesgs The number of messages queued on this port.
backlog The number of messages which may be queued to this port without causing the sender to block.
owner Returned as true IFF (if and only if) the task is owner
of the port.
receiver Returned as true IFF the task is the receiver of this port.
Description:
Returns the current status associated with task's port right named name.
If receiver isnt true, then the 'enabled', 'num-mesg', and 'backlog' arguments dont return anything meaningful.
Returns:
ERIC_SUCCESS The call succeeded.
ERIC_INVALID_ACCOUNT task was invalid or name does not name
a valid port.
int kPort::set_backup( kTask* task,
long primary,
long backup,
long& previous );
Arguments:
task The task owning the named port right
primary task's name for the primary port
backup The new backup port to be set
previous The previous backup port.
Description:
A backup port provides an automatic mechanism to transfer port receive rights to another task or thread in the event of a primary port's attempted death.
To be more precise, if a primary port has a backup port, and the primary would have been destroyed by the deallocation of its receive rights, then instead the receive right for the primary port is sent in a notify message, (NOTIFY_PORT_DESTROYED) to the backup port.
A newly allocated port does not have a backup port. The set_backup() call changes the backup of the 'primary' port. The target 'task' must hold receive rights for the 'primary' port. The caller receives send rights for the previous backup port of PORT_NULL if the target did not have a backup. set_backup() works atomically, so that if one backup port is exchanged for another, the primary port is never left without a backup.
When the primary port is sent in a notify message to the backup port, the primary port is left without a backup port. When the task receives the notification and the receive rights to the primary port, it may wish to use set_backup() to reestablish the same or a different backup port.
If the backup port is destroyed before the primary, then the primary port is left without a backup. (A subsequent set_backup() call would return PORT_NULL).
Returns:
ERIC_SUCCESS The call succeeded
ERIC_NOT_RECEIVER
primary doesnt name receive rights in task. ERIC_INVALID_ARGUMENT task was invalid, or backup did not name a valid port.
int kPort::set_allocate( kTask* task, long& set_name );
Arguments:
task The task in which the new port set is created
name The task's name for the new port set.
Description:
causes a port set to be created for the specified task; the resulting set's name is returned in set_name.
Returns:
ERIC_SUCCESS The succeeded.
ERIC_INVALID_ARGUMENT 'task' was invalid
ERIC_RESOURCE_SHORTAGE The kernel ran out of memory
int kPort::set_add( kTask* task, long set_name );
Arguments:
task The task owning the port set and port right
set_name task's name for the port set
Description:
Moves the current port into the named port set. 'task' must have receive rights for the port. If the port is already a member of another port set, it is removed from that set first.
Returns:
ERIC_SUCCESS The call succeeded
ERIC_NOT_RECEIVER port name doesnt have receive rights in
'task'
ERIC_INVALID_ARGUMENT 'task' was invalid or 'set_name' does
not name a valid port set or port_name does not name a valid port.
int kPort::set_remove( kTask* task );
int kPort::set_remove( kTask* task, long name );
Arguments:
task The task owning the receive rights and port set.
name task's name for the receive rights to be removed.
Description:
Removes the named port from a port set.
'task' must have receive rights for the port, and the port must be amember of a port set.
Returns:
ERIC_SUCCESS The call succeeded
ERIC_NOT_RECEIVER port name doesnt have receive rights in
task.
ERIC_NOT_IN_SET The port isnt a member of a set
ERIC_INVALID_ARG task was invalid or port name does not name
a valid port.
int kPort::set_status( kTask* task, long set_name,
long& members, int& membersCnt );
Description:
Returns the members of a port set.
'members' is an array this is automatically allocated when the reply message is received. The user may wish to deallocate it when the data is no longer needed.
Returns:
ERIC_SUCCESS The call succeeded.
ERIC_INVALID_ARG 'task' was invalid or invalid port set.
int kPort::insert_snd( kTask* task, long name );
int kPort::insert_rcv( kTask* task, long name );
task The task getting the new rights
name The name by which 'task' will know the new rights
Description:
Both give task rights with a specific name.
If task already has rights named 'name', then the operation will fail. 'name' cannot be a distinguished value like PORT_NULL. insert_snd() inserts send rights, and insert_receive inserts receive and ownership rights.
Returns:
ERIC_SUCCESS The call succeeded
ERIC_NAME_EXISTS task already has a right named 'name'
ERIC_FAILURE task already has rights to my_port
ERIC_INVALID_ARG task was invalid or new_name was an invalid
name N.B. There is no way to insert just receive rights, or just ownership
rights.
int kPort::extract_snd(kTask* task, long name, long port);
int kPort::extract_rcv(kTask* task, long name, long port);
Arguments:
task The task whose rights the caller takes
name The name by which task knows the rights port Rights returned
to the caller
Description:
Remove task's rights for a port amd return the rights to the caller.
Returns:
ERIC_SUCCESS The call succeeded
ERIC_INVALID_ARG Task was invalid or name does not match a
port for which task has the required rights.
Note: There is no way to extract just recieve rights, or just ownership rights.