home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / mach / doc / unpublished / netmemory.man.Z / netmemory.man
Encoding:
Text File  |  1992-09-01  |  7.0 KB  |  211 lines
  1.  
  2.  
  3.  
  4. NETMEMORY(3)        UNIX Programmer's Manual         NETMEMORY(3)
  5.  
  6.  
  7.  
  8. NAME
  9.      netmemory_create - create a netmemory object
  10.      netmemory_cache - create a mach memory object from a netmemory object
  11.      netmemory_destroy - destroy a netmemory object
  12.  
  13. SYNOPSIS
  14.      #include <servers/netmemory.h>
  15.  
  16.      netmemory_return_t netmemory_create(netmemory_server, object_size,
  17.                                          netmemory_object, netmemory_control)
  18.              port_t          netmemory_server;
  19.              vm_size_t       object_size;
  20.              port_t          *netmemory_object;
  21.              port_t          *netmemory_control;
  22.  
  23.      netmemory_return_t netmemory_cache(netmemory_server, netmemory_object,
  24.                                         memory_object)
  25.              port_t          netmemory_server;
  26.              port_t          netmemory_object;
  27.              port_t          *memory_object;
  28.  
  29.      netmemory_return_t netmemory_destroy(netmemory_control)
  30.              port_t          netmemory_control;
  31.  
  32.  
  33. ARGUMENTS
  34.      netmemory_server
  35.                     Port to the Network Shared Memory Server,
  36.                     obtainable via the netname server (see _n_e_t_-
  37.                     _n_a_m_e(_3) ) under the name netmemoryserver.
  38.  
  39.      object_size    Size in bytes of the netmemory object to be
  40.                     created.
  41.  
  42.      netmemory_object
  43.                     Port representing the netmemory object, for
  44.                     use with netmemory_cache.
  45.  
  46.      memory_object  Mach memory object, for use by vm_map.
  47.  
  48.      netmemory_control
  49.                     Port that is used for control operations on
  50.                     the netmemory object.
  51.  
  52.  
  53. DESCRIPTION
  54.      The Network Shared Memory Server allows tasks on different
  55.      machines to share virtual memory.  It also provides a
  56.      mechanism for arbitrary tasks on the same machine to share
  57.      memory.
  58.  
  59.      To share memory between tasks using the netmemory server,
  60.      first create a netmemory object with the netmemory_create
  61.      call. This netmemory object can be distributed to all
  62.      interested tasks either directly by IPC between tasks or
  63.      indirectly by using a service such as the netname server.
  64.  
  65.      Each task should then find its local netmemory server, and
  66.      call netmemory_cache on the local server with the netmemory
  67.      object to obtain a local mach memory object corresponding to
  68.      the netmemory object.  The netmemory_cache call allows the
  69.      netmemory servers to use more efficient and more distributed
  70.      protocols for maintaining object consistency than the stan-
  71.      dard memory manager interface.
  72.  
  73.      Finally, the resulting memory object should be given to
  74.      vm_map to map the object into the caller's address space.
  75.      gain, the netmemory object is only for use by
  76.      netmemory_cache; it should not be handed directly to vm_map.
  77.  
  78.      The netmemory object can be explicitly destroyed by calling
  79.      netmemory_destroy on the netmemory_control port. This call
  80.      is not necessary on the current implementation of the net-
  81.      memoryserver which cleans up a netmemory object after the
  82.      last kernel has unmapped the object.
  83.  
  84.      The current netmemory server is actually a compatability
  85.      front-end to the External Memory Manager server (see
  86.      _x_m_m_s_e_r_v_e_r(_8) ).
  87.  
  88.  
  89. EXAMPLE
  90.      The following is a routine which demonstrates how to use the
  91.      netmemory server.
  92.  
  93.      /*
  94.       * Create and map a shared object of given size with
  95.       * netname "object_name".
  96.       *
  97.       * One task (the "master") should call this routine with
  98.       * hostname = 0; the routine will then create a netmemory
  99.       * object and register it with the netname server under the
  100.       * supplied object name. All other tasks (the "slaves") call
  101.       * this routine with the hostname where the master lives.
  102.       */
  103.      kern_return_t
  104.      map_object(object_name, hostname, address, size, anywhere)
  105.          char *object_name;
  106.          char *hostname;
  107.          vm_offset_t *address;
  108.          vm_size_t size;
  109.          boolean_t anywhere;
  110.      {
  111.          kern_return_t kr;
  112.          port_t netmemory_server;
  113.          port_t memory_object;
  114.          port_t netmemory_object;
  115.          port_t netmemory_control;
  116.  
  117.          /*
  118.           * Find the local netmemory server.
  119.           * (If this routine is used a lot, this value can be cached.)
  120.           */
  121.          kr = netname_look_up(name_server_port, "", "netmemoryserver",
  122.                               &netmemory_server);
  123.          if (kr) {
  124.              return kr;
  125.          }
  126.  
  127.          /*
  128.           * If a hostname is provided, then we are the slave and thus we
  129.           * simply look up the netmemory object on the given host by using
  130.           * the object name.
  131.           *
  132.           * If a hostname is not provided, then we are the master and thus
  133.           * have the responsibility of creating a netmemory object and
  134.           * registering it with the netname service under the given object
  135.           * name.
  136.           */
  137.          if (hostname) {
  138.              kr = netname_look_up(name_server_port, hostname, object_name,
  139.                                   &netmemory_object);
  140.              if (kr) {
  141.                  return kr;
  142.              }
  143.          } else {
  144.              kr = netmemory_create(netmemory_server, size, &netmemory_object,
  145.                                    &netmemory_control);
  146.              if (kr) {
  147.                  return kr;
  148.              }
  149.              kr = netname_check_in(name_server_port, object_name, PORT_NULL,
  150.                                    netmemory_object);
  151.              if (kr) {
  152.                  netmemory_destroy(netmemory_control);
  153.                  return kr;
  154.              }
  155.          }
  156.  
  157.          /*
  158.           * Cache the object locally. Note that even the master must do this.
  159.           */
  160.          kr = netmemory_cache(netmemory_server, netmemory_object,
  161.                               &memory_object);
  162.          if (kr) {
  163.              return kr;
  164.          }
  165.  
  166.          /*
  167.           * Map the object, either anywhere or at the supplied address.
  168.           */
  169.          if (anywhere) {
  170.              *address = 0; /* must be set */
  171.          }
  172.          kr = vm_map(task_self(), address, size, 0, anywhere,
  173.                      memory_object, 0, FALSE,
  174.                      VM_PROT_DEFAULT, VM_PROT_DEFAULT, VM_INHERIT_SHARE);
  175.          if (kr) {
  176.              return kr;
  177.          }
  178.          return KERN_SUCCESS;
  179.      }
  180.  
  181.  
  182. FILES
  183.      <servers/netmemory.h>
  184.  
  185.  
  186. DIAGNOSTICS
  187.      NETMEMORY_SUCCESS        operation succeeded.
  188.  
  189.      NETMEMORY_RESOURCE       the server could not allocate the
  190.                               resources necessary to perform the
  191.                               operation.
  192.  
  193.      NETMEMORY_BAD_PARAMETER  an invalid parameter was supplied.
  194.  
  195.  
  196. SEE ALSO
  197.      _v_m__m_a_p(_2), _n_e_t_n_a_m_e(_3), _n_e_t_m_e_m_o_r_y_s_e_r_v_e_r(_8), _x_m_m_s_e_r_v_e_r(_8)
  198.  
  199.  
  200. BUGS
  201.      Older versions of the netmemoryserver tend to leak
  202.      resources.
  203.  
  204.  
  205. HISTORY
  206.      30-Jun-88  Joseph S. Barrera (jsb)
  207.           Created.
  208.  
  209.      20-Feb-91  Joseph S. Barrera (jsb)
  210.           Revised.
  211.