2.4 System resources

\subsection{System resource overview} Each resource in the system supports a set of well-defined operations. Namely, those provided by building blocks that we have seen before and a few others like nameof, to get the resource name, freeze, to get the state of the object and defer any further invocations, melt, to recreate a frozen object, and ``<<'', which will print a representation of the resource state.

<Off resource. >= (U->)
// A system resource.
//
class off_Resource : public off_Lockable {
private:
  <Off private members for integrity checked resources. >
  <Off private members for protected objects. >
  <Off private members for reference counting objects. >
  <Other private members of off_Resource. >
protected:
  <Other protected members of off_Resource. >
  <Off protected methods for integrity checked resources. >
  <Off protected methods for reference counting objects. >
  <Other protected methods of off_Resource. >
public:

  <Off public methods for reference counting objects. >
  <Off public methods for protected objects. >
   

  // Every resource (be it simple or compound) is named and is able to be
  //  dumped for inspection and frozen/melted. 
  // Names it.
  virtual const char *nameof(void)=0;
  // Names its class.
  virtual const char *kindof(void) { return get_magic().nameof(); }
  // Gives its URL
  virtual const char *get_url(void)=0;
  // Dumps it.
  friend OStr &operator<<(OStr &s, const off_Resource &r);

  <Other public methods of off_Resource. >
};

Defines off_Resource (links are to index).

We have already introduced a few dependencies.

<Off resource dependencies. >= (U->) [D->]
#include <flux/types.h>         // for boolean_t natural_t et al.
#include <klib/Lockable.h>      // for Lockable.
#include <klib/prot.h>          // for off_Protection et al.
#include <klib/Magic.h>         // for off_Magic et al.
#include <klib/err.h>           // for err_t and error numbers.
#include <klib/str.h>           // for OStr

Also, we should mention that some resource members are initialized at allocation time with the information provided by system users. That information includes the protection for the resource, the resource identifier and an identifier used to identify the user-level entity responsible for the object after its allocation; we name such entity the object domain.

Being the \emph{Portal} the IPC mechanism provided by the kernel, the domain identifier is indeed a portal identifier of type off_prtl_id_t. By doing that, we can have the kernel performing upcalls to either user-level or in-kernel domain servers which will be responsible for allocated system resources. Besides, the meaning of the domain abstraction is defined by the user and not by the kernel, as will be discussed in section .

<Other private members of off_Resource. >= (<-U)
off_prtl_id_t r_domain;         // Domain for the resource
off_id_t r_id;                  // Resource identifier.

<Other public methods of off_Resource. >= (<-U) [D->]
// Returns the resource domain.
const off_prtl_id_t &get_domain( void ) const { return r_domain; } 
// Returns the resource identifier.
const off_id_t  &get_id(void) const { return r_id; }

The domain might be reset so we provide this method.

<Other protected methods of off_Resource. >= (<-U) [D->]
// Sets the resource domain.
void set_domain(const off_prtl_id_t &d) { r_domain=d; }
// Sets the resource identifier.
void     set_id(const off_id_t &id) { r_id = id; }

<Off resource dependencies. >+= (U->) [<-D->]
#include <klib/ids.h>           // for off_prtl_id_t et al.

The constructor does the job.

<Other protected methods of off_Resource. >+= (<-U) [<-D->]
// Creates a resource.
off_Resource(const off_Protection &p, 
             const off_prtl_id_t &domain, const off_id_t       &id,
             const off_magic_t magic ):
  <Off initialization for integrity checked resources with magic. >,
  r_domain(domain), r_id(id),
  <Initialize other aggregate members of off_Resource. >
{ 
   <Off initialization for p protected objects. >
   <Off initialization for reference counting objects. >
}

A convention is used through the kernel, resources used for the kernel itself belong to a ``kernel'' domain, thus available resources maintain always a NULL domain.

<Other public methods of off_Resource. >+= (<-U) [<-D->]
// Is this resource free?
boolean_t is_free(void) const { return r_domain == OFF_PRTL_NULL; }

Finally, this dump routine is provided as a debug aid.

<off_Resource::operator<< implementation. >= (U->)
// Dumps the resource.
OStr &operator<<(OStr &s, const off_Resource &r)
{
  s << (r.is_locked()?"L ":"u ") << "RC=" << r.get_num_refs() << " ";
  s << "F=" << fmt("0x%02x",r.r_flags) <<" " << nl;
  s << "id=" << r.get_id() << " ";
  return s;
}

\subsubsection{Resources for plain users}

These are the common entry points for every system resource.

<Off resource for users. >= (U->)
// Exported resource interface. 
//
class off_uResource {
private:
  off_Resource &u_resource;
public:
  off_uResource(off_Resource &r) : u_resource(r) {;}
  <Other public methods of off_uResource. >

};

Defines off_uResource (links are to index).

\subsubsection{Resource \cpp{} source files}

Resource code is contained in klib/Resource.h and klib/Resource.C source files.

<Resource.h*>=
<Read the literate code instead warning. >
#ifndef __OFF_RESOURCE_H
#define  __OFF_RESOURCE_H 1

<Off resource dependencies. >

<Off resource flag bits. >

#ifdef __KERNEL__

<Off resource. >

#endif // __KERNEL__

<Off resource for users. >

#endif // __OFF_RESOURCE_H

<Resource.C*>=
<Read the literate code instead warning. >

#include <klib/Resource.h>      // Exported interface.
<Off resource implementation dependencies. >

<off_Resource::operator<< implementation. >
<Implementation of other methods of off_Resource. >