Mailboxes

In the previous articles, we've discussed mailboxes conceptually. As described, UOS mailboxes are not related to email, but are virtual devices used for interprocess communication. In this article, we will look at the code that implements mailboxes.

type TMailbox = class( TFiP_File )
                    public // Constructors and destructors...
                        constructor Create( _Kernel : TUOS_Kernel ) ;
                        destructor Destroy ; override ;

                    public // API...
                        Protection : cardinal ;
                        Owner : int64 ;
                        Max_Storage : int64 ;
                        Permanent : boolean ;
                        Kernel : TUOS_Kernel ;
                        Device : Devices.TDevice ;

                    private // Instance data...
                        Current_Storage : int64 ;
                        Deleted : boolean ; // True if marked for deletion
                        Queue : TList ;

                    public // API...
                        function Is_Class( Name : PChar ) : boolean ; override ;

                        function Delete : TUnified_Exception ;

                        function Read( Stream : longint ;
                            Position : TStore_Address64 ;
                            Length : TStore_Size64 ; var Buff ;
                            Flags : longint ) : TStore_Size64 ; override ;

                        function Write( Stream : longint ;
                            Position : TStore_Address64 ;
                            Length : TStore_Size64 ; var Buff ;
                            Flags : longint ) : TStore_Size64 ; override ;

                        procedure Check_Delete ;
                end ;

We start with the mailbox class. Each mailbox created on UOS will have an instance of this class.

constructor TMailbox.Create( _Kernel : TUOS_Kernel ) ;

begin
    inherited Create( _Kernel ) ;

    Kernel := _Kernel ;
    Queue := TList.Create ;
    Device := Devices.TDevice.Create ;
    Device.Mounted := True ;
    Device.Info.Flags := DFC_Stream ;
end ;


destructor TMailbox.Destroy ;

var I : integer ;

begin
    for I := 0 to Queue.Count - 1 do
    begin
        TMessage( Queue[ I ] ).Free ;
        Queue[ I ] := nil ;
    end ;
    Queue.Free ;
    Device.Free ;
    if( Permanent ) then
    begin
        I := TUOS_FIP( Kernel.FIP ).Permanent_Mailboxes.Indexof( self ) ;
        TUOS_FIP( Kernel.FIP ).Permanent_Mailboxes[ I ] := nil ;
    end else
    begin
        I := TUOS_FIP( Kernel.FIP ).Temporary_Mailboxes.Indexof( self ) ;
        TUOS_FIP( Kernel.FIP ).Temporary_Mailboxes[ I ] := nil ;
    end ;

    inherited Destroy ;
end ;

The constructor initializes data and also sets up a TDevice instance for the mailbox. Physical devices have a TDevice instance set up for them during system startup, but mailboxes are virtual and when one is created, we need a device instance for each one. As a device, a mailbox is always mounted and is considered a stream. The Queue list will contain the message queue. On destruction, we free up each individual message before freeing the queue list. Finally, we remove the mailbox from the appropriate list. The FIP has two lists: one for permanent mailboxes and one for temporary mailboxes.

function TMailbox.Is_Class( Name : PChar ) : boolean ;

var _N : string ;

begin
    _N := Name ;
    _N := lowercase( _N ) ;
    Result := ( _N = 'TMailbox' ) ;
    if( not Result ) then
    begin
        Result := inherited Is_Class( Name ) ;
    end ;
end ;


function TMailbox.Delete : TUnified_Exception ;

begin
    Deleted := True ;
end ;

The Is_Class method is similiar to all previous instances of such method. The Delete method simply markes the Mailbox for deletion. It doesn't actually delete the mailbox since there may be open channels to the mailbox. The deletion will occur later. In the case of permanent mailboxes, the deletion occurs as the result of a system service call. For temporary mailboxes, the deletion occurs when the last handle to the mailbox is closed.

unction TMailbox.Write( Stream : longint ; Position : TStore_Address64 ;
    Length : TStore_Size64 ; var Buff ; Flags : longint ) : TStore_Size64 ;

var FIP : TUOS_FIP ;
    I : integer ;
    Request : TUOS_IO_Request ;
    S : TMessage ;
    St : string ;
    V : int64 ;

begin
    // Check quota...
    if( Length > Max_Storage - Current_Storage ) then // No room in mailbox
    begin
        Set_Last_Error( Create_Error( UOSErr_No_Room_On_Device ) ) ;
        Result := 0 ;
        exit ;
    end ;

    // Check protection...
    if( not Kernel.USC.Validate_Protection( Kernel.PID, FAB_V_PUT, Device.Owner.Owner, 
        Device.Owner.Protections, 0{ACL} ) ) then
    begin
        Set_Last_Error( Create_Error( UOSErr_Protection_Violation ) ) ;
        Result := 0 ;
        exit ;
    end ;

This method does the write operation to the mailbox. First we check to see if the length of the data would cause the total mailbox data size to exceed its maximum quota. If so, we exit with an error. Then we check that the user isn't violating the protection of the mailbox.

    // Create queue entry...
    Current_Storage := Current_Storage + Length ;
    setlength( St, Length ) ;
    move( Buff, PChar( St )[ 0 ], Length ) ;
    S := TMessage.Create ;
    S.Set_Value( St ) ;
    S.Time := HAL.Timestamp ;
    PID := Kernel.PID ;
    S.PID := PID ;
    S.UIC := Kernel.USC.Get_Process_Info( PID, JPI_UIC ) ;
    S.Privileges := Kernel.USC.Get_Process_Info( PID, JPI_CURPRIV ) ;
    Queue.Add( S ) ;
    Result := Length ;

Next we create a TMessage instance to store the data. We'll cover this class later in the article, but essentially it is nothing more than a way to store a string as an object. We copy the data into a string, write it into the object instance and then add the object to Queue, which is a TList that holds all messages sent to the mailbox. Each write to the mailbox is a single message in the queue. Then we return the length of the data, indicating that the whole data was written. Reads and writes are atomic operations: either the entire amount is read or written, or nothing is.

Also notable here is the assignment of Time, PID, UIC, and Privileges to the message instance. The timestamp allows a mailbox reader to know exactly when the message was sent (written). The PID lets it know which process sent the message. But why pass the UIC and Privileges since those could be obtained based on the process ID? The reason is that the process could have ended before the message was processed, leaving that information unavailable. A message receiver may want to know which user sent the message. Further, it is possible (though unlikely) that when a new process is created, it might be assigned a previously used ID, which leaves the original UIC and privileges unavailable. The reason for including privileges is not only because the originating process may no longer be available, but because the current privileges (which is what is passed) can change over time even with given process. Some operations may require certain privileges (such as OPCOM operations), and the reader may need to know if the sender was authorized to make the request.

    // Notify FIP of status change of device...
    FIP := TUOS_FIP( Kernel.FIP ) ;
    V := IT_Status ;
    V := V shl 8 ;
    V := V or GDT_Mailbox ;
    V := V shl 16 ;
    if( not Permanent ) then
    begin
        V := V or 1 ; // MAILB
    end ;
    V := V shl 16 ;
    if( Permanent ) then
    begin
        V := V or FIP._Permanent_Mailboxes.Indexof( self ) ;
    end else
    begin
        V := V or FIP._Temporary_Mailboxes.Indexof( self ) ;
    end ;
    V := V shl 16 ;
    V := V or Interrupt_IO ;
    FIP.Interrupt( V ) ;
end ;

Lastly, we send an interrupt notice to the File Processor. This allows any pending read operations for the mailbox to complete now that there is data available.

function TMailbox.Read( Stream : longint ; Position : TStore_Address64 ;
    Length : TStore_Size64 ; var Buff ; Flags : longint ) : TStore_Size64 ;

var FIP : TUOS_FIP ;
    I : integer ;
    Request : TUOS_IO_Request ;
    S : TMessage ;
    V : int64 ;

begin
    // Check protection...
    if( not Kernel.USC.Validate_Protection( Kernel.PID, FAB_V_GET, Device.Owner.Owner, 
        Device.Owner.Protections, 0{ACL} ) ) then
    begin
        Set_Last_Error( Create_Error( UOSErr_Protection_Violation ) ) ;
        Result := 0 ;
        exit ;
    end ;

    if( Queue.Count = 0 ) then // No data in mailbox
    begin
        Set_Last_Error( Create_Error( UOSErr_Read_Past_End ) ) ;
        Result := 0 ;
        exit ;
    end ;

Thia method allows reading from a mailbox. First we check that the mailbox protections don't prevent us from reading. Then we check to see if the queue is empty. If either situation exists, we exit with an error.

    // Read from mailbox...
    S := TMessage( Queue[ 0 ] ) ;
    if( Length > S.Len ) then
    begin
        Length := S.Len ;
    end ;
    Result := Length ;
    move( S.Contents[ 0 ], Buff, Length ) ;
    Current_Storage := Current_Storage - Length ;

    // Remove message from mailbox...
    S.Free ;
    Queue.Delete( 0 ) ;

Next we get the first TMessage instance from the queue. Since we treat the list as a FIFO queue, we take messages from the beginning of the list (index 0) and add them to the end of the list in the write method. Once we write the data to the user's buffer, we remove the item from the queue, and destroy the instance.

    // Notify FIP of status change of device...
    FIP := TUOS_FIP( Kernel.FIP ) ;
    V := IT_Status ;
    V := V shl 8 ;
    V := V or GDT_Mailbox ;
    V := V shl 16 ;
    if( not Permanent ) then
    begin
        V := V or 1 ; // MAILB
    end ;
    V := V shl 16 ;
    if( Permanent ) then
    begin
        V := V or FIP._Permanent_Mailboxes.Indexof( self ) ;
    end else
    begin
        V := V or FIP._Temporary_Mailboxes.Indexof( self ) ;
    end ;
    V := V shl 16 ;
    V := V or Interrupt_IO ;
    FIP.Interrupt( V ) ;
end ;

As we saw in the write method, we send an interrupt to the File Processor to handle unblocking any process waiting on data to read from the mailbox.

procedure TMailbox.Check_Delete ;

begin
    if( not Any_Handles ) then // No more handles...
    begin
        if( Permanent ) then
        begin
            if( Deleted ) then
            begin
                Free ;
            end ;
        end else
        begin
            Free ;
        end ;
    end ;
end ;

This routine is used to check to see if the mailbox should be deleted. Deletion will only happen if the mailbox has been marked for deletion or is a temporary mailbox with no attached handles.

type TMessage = class( TString )
                    public // API...
                        Time : int64 ;
                        PID : TPID ;
                        UIC : int64 ;
                        Privileges : int64 ;

                        procedure Set_Value( St : string ) ;
                end ;

procedure TMessage.Set_Value( St : string ) ;

begin
    _Value := St ;
end ;

TMessage is a descendent of the TString class. It adds the additional contextual information we talked about above. It also contains a method that allows assigning a value via a Pascal string rather than a pchar.

There are some other code changes needed to support mailboxes in different parts of the File Processor, and we will address those in a future article (or two).

In the next article, we will look at the SYS_BRKTHRU system service, which is used by REPLY.