externalResource-class    package:externalVector    R Documentation

_C_l_a_s_s "_e_x_t_e_r_n_a_l_R_e_s_o_u_r_c_e", _b_a_s_e _c_l_a_s_s _f_o_r _e_x_t_e_r_n_a_l _r_e_s_o_u_r_c_e
_a_l_l_o_c_a_t_e_d _b_y _a_n _e_x_t_e_r_n_a_l_A_l_l_o_c_a_t_o_r

_D_e_s_c_r_i_p_t_i_o_n:

     Class '"externalResource"' is a virtual class with no slots.
     External allocators, represented by subclasses of class
     '"externalAllocator"' can only allocate external pointers
     contained in objects from a subclass of '"externalResource"'.

_O_b_j_e_c_t_s _f_r_o_m _t_h_e _C_l_a_s_s:

     A virtual Class: No objects may be created from it.

_M_e_t_h_o_d_s _f_o_r _t_h_e _v_i_r_t_u_a_l _c_l_a_s_s "_e_x_t_e_r_n_a_l_R_e_s_o_u_r_c_e":

     These methods are defined for the virtual class "externalResource"
     and need not be redefined by its subclasses.

     Signature components for the methods are:

       resource  The class "externalResource"
       alloc     The class "missing"
       ptr       The class "externalptr"
       size      The class "ANY"
       type      The class "ANY"
       copy      The class "logical"
       value     The class "ANY"

     The argument 'alloc' has the class "missing" wherever it appears
     in these methods. That means, to invoke these methods, the
     argument 'alloc' must be ommitted from the call and to use any of
     the additional arguments, they must be specfied by name. For
     example, use 'allocate(resource, size=size, type=type)' and not
     'allocate(resource, size, type)'.

     Description of the methods:


     _a_l_l_o_c_a_t_e_d_T_y_p_e(_r_e_s_o_u_r_c_e): Returns 'NULL'. 

     _a_l_l_o_c_a_t_e(_r_e_s_o_u_r_c_e, _a_l_l_o_c, _s_i_z_e, _t_y_p_e, ...): Allocate the external
          pointer in resource using the default allocator for
          'resource'. If 'type' is a basic vector object, then allocate
          an object of same mode with length 'size'. Otherwise allocate
          'size' bytes of raw memory. The 'resource' object is
          initialized by a call to 'initializeResource'. 

     _d_e_a_l_l_o_c_a_t_e(_r_e_s_o_u_r_c_e, _a_l_l_o_c): Ask the default allocator to
          deallocate the memory in 'resource'. The result is allocator
          dependant. 

     _e_x_t_e_r_n_a_l._s_i_z_e Return the argument 'size' used in the last call to
          'allocate' for 'resource' 

     _e_x_t_e_r_n_a_l._s_i_z_e<-(_r_e_s_o_u_r_c_e, _c_o_p_y, _a_l_l_o_c, _v_a_l_u_e): If 'value' is same
          as 'external.size(resource)', then no action is taken.
          Otherwise, reallocate the memory in 'resource' using the
          default allocator with new size 'value' and the same type as
          earlier. If 'copy' is 'TRUE' (the default), then the new
          memory is initialized to the content of  the old memory for
          the minimum of old and new sizes. Content of any
          uninitialized memory is undefined. Under any circumstance,
          the inherent type of the allocated memory remains the same as
          its initial value. 

     _i_n_i_t_i_a_l_i_z_e(._O_b_j_e_c_t): Code called by new("resourceSubclass", ...)
          if "resourceSubclass" is a subclass of "externalResource" and
          either has no 'initialize' method of its own or its
          'initialize' method has 'callNextMethod()' in its body.
          Returns the result of 'allocate(.Object, ...)'

     _r_e_i_n_i_t_i_a_l_i_z_e_P_o_i_n_t_e_r(_r_e_s_o_u_r_c_e, _a_l_l_o_c): If the object 'resource' was
          saved as an R image (by serialization code, by saving the R
          workspace, or by an explicit call to 'save') then the raw
          memory pointer in any '"externalptr"' object in it would be
          set to '0'. This method tries to reinitialize the raw memory
          pointer. The exact result is allocator dependant. 

_V_i_r_t_u_a_l _M_e_t_h_o_d_s:

     Attempt to execute these methods would result in an error unless
     they have been redefined for a subclass of '"externalResource"'.

     Signature components for implementation of the methods:

       resource  A subclass of "externalResource"
       ptr       The class "externalptr"
       size      The class "ANY"
       type      The class "ANY"

     Description of the virtual methods:


     _a_l_l_o_c_a_t_e_d_S_i_z_e(_r_e_s_o_u_r_c_e): Size of memory to be allocated for
          'resource'. If 'allocatedType(resource)' is an R basic vector
          type, then the size is the length of the vector. Otherwise
          the size is the total number of bytes. 

     _a_l_l_o_c_a_t_o_r(_r_e_s_o_u_r_c_e): The allocator to be used by default with this
          'resource'. 

     _g_e_t_P_o_i_n_t_e_r(_r_e_o_u_r_c_e): Return the '"externalptr"' associated with
          this 'resource'. 

     _i_n_i_t_i_a_l_i_z_e_R_e_s_o_u_r_c_e(_r_e_s_o_u_r_c_e, _p_t_r, _s_i_z_e, _t_y_p_e, ...): Intialize
          'resource' with 'ptr' of type '"externalptr"'. The 'size' and
          'type' arguments are identical to that obtained from previous
          calls to 'allocatedSize(resource)' and
          'allocatedType(resource)'. 

_O_t_h_e_r _V_i_r_t_u_a_l _M_e_t_h_o_d_s:

     These methods must be redefined for subclasses for
     '"externalAllocator"'. It is not necessary to define them for
     specific subclasses of '"externalResource"'.

     Signature components for implementation of the methods:

       resource  The class "externalResource"
       alloc     A subclass of "externalAllocator"
       size      The class "ANY"
       type      The class "ANY"
       copy      The class "logical"
       value     The class "ANY"

     Description of the virtual methods:


     _a_l_l_o_c_a_t_e(_r_e_s_o_u_r_c_e, _a_l_l_o_c, _s_i_z_e, _t_y_p_e, ...): Allocate the external
          pointer in 'resource' using the allocator 'alloc'. 

     _d_e_a_l_l_o_c_a_t_e(_r_e_s_o_u_r_c_e, _a_l_l_o_c): Ask the allocator 'alloc' to
          deallocate the memory in 'resource'. 

     _e_x_t_e_r_n_a_l._s_i_z_e Return the size of the allocated memory in
          'resource'. 

     _e_x_t_e_r_n_a_l._s_i_z_e<-(_r_e_s_o_u_r_c_e, _c_o_p_y, _a_l_l_o_c, _v_a_l_u_e): Reallocate the
          memory in 'resource' using the allocator 'alloc'. 

     _r_e_i_n_i_t_i_a_l_i_z_e_P_o_i_n_t_e_r(_r_e_s_o_u_r_c_e, _a_l_l_o_c): If the raw memory pointer in
          'resource' is zero, try to reinitialize it. 

_A_u_t_h_o_r(_s):

     Saikat DebRoy <saikat@stat.wisc.edu>

_S_e_e _A_l_s_o:

     'externalAllocator-class' for more details on how to use an
     allocator with objects from subclasses of '"externalResource"'.

     'gcAllocator-class' for an example of a simple subclass of
     '"externalResource"'.

     'setVirtualMethod' for more on virtual methods.

