gcAllocator-class       package:externalVector       R Documentation

_C_l_a_s_s "_g_c_A_l_l_o_c_a_t_o_r", _m_e_m_o_r_y _a_l_l_o_c_a_t_o_r _c_l_a_s_s _f_o_r _e_x_t_e_r_n_a_l _r_e_s_o_u_r_c_e_s

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

     A memory allocator class for external resources that allocates
     memory using R memory management system. The allocated memory is
     freed by the R garbage collector when all refernce to it is
     removed.

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

     Objects can be created by calls of the form 'new("gcAllocator")'.

_E_x_t_e_n_d_s:

     Class '"externalAllocator"', directly.

_M_e_t_h_o_d_s:

     Signature components for the methods:

       resource  The class "externalResource"
       alloc     The class of "gcAllocator"
       size      The class "ANY"
       type      The class "ANY"
       copy      The class "logical"
       value     The class "ANY"

     Description of the 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'. 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 allocation
          is done by creating an R basic vector with same class as type
          and storing it in the protected field of the newly created
          external pointer. Ends with a call to 'initializeResource' to
          initialize the 'resource' object. 

     _d_e_a_l_l_o_c_a_t_e(_r_e_s_o_u_r_c_e, _a_l_l_o_c): Replace the protected field of
          'resource@ptr' with 'R_NilValue'. 

     _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): If 'value' is same
          as 'external.size(resource)', then no action is taken.
          Otherwise, reallocate the memory in 'resource' with new size
          'value'. 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. 

     _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 reinitializes the memory (if
          possible) by using the protected field of the external
          pointer. 

_E_x_a_m_p_l_e_s:

     library(externalVector)
     ## set a storage class
     setClass("testStorage",
              representation(ptr="externalptr"),
              contains="externalResource")
     setMethod("initializeResource", "testStorage",
               function(resource, ptr, size, type, ...)
            {
                resource@ptr <- ptr
                resource
            })
     setMethod("allocator", "testStorage",
               function(resource)
               new("gcAllocator"))
     setMethod("getPointer", "testStorage",
               function(resource)
               resource@ptr)
     setMethod("allocatedSize", "testStorage",
               function(resource)
               32)
     ## Now create an object from the class
     x <- new("testStorage")
     x
     external.size(x)
     external.size(x) <- 64
     x
     external.size(x)
     deallocate(x)
     x
     external.size(x)

