NETMEMORY(3) UNIX Programmer's Manual NETMEMORY(3) NAME netmemory_create - create a netmemory object netmemory_cache - create a mach memory object from a netmemory object netmemory_destroy - destroy a netmemory object SYNOPSIS #include netmemory_return_t netmemory_create(netmemory_server, object_size, netmemory_object, netmemory_control) port_t netmemory_server; vm_size_t object_size; port_t *netmemory_object; port_t *netmemory_control; netmemory_return_t netmemory_cache(netmemory_server, netmemory_object, memory_object) port_t netmemory_server; port_t netmemory_object; port_t *memory_object; netmemory_return_t netmemory_destroy(netmemory_control) port_t netmemory_control; ARGUMENTS netmemory_server Port to the Network Shared Memory Server, obtainable via the netname server (see _n_e_t_- _n_a_m_e(_3) ) under the name netmemoryserver. object_size Size in bytes of the netmemory object to be created. netmemory_object Port representing the netmemory object, for use with netmemory_cache. memory_object Mach memory object, for use by vm_map. netmemory_control Port that is used for control operations on the netmemory object. DESCRIPTION The Network Shared Memory Server allows tasks on different machines to share virtual memory. It also provides a mechanism for arbitrary tasks on the same machine to share memory. To share memory between tasks using the netmemory server, first create a netmemory object with the netmemory_create call. This netmemory object can be distributed to all interested tasks either directly by IPC between tasks or indirectly by using a service such as the netname server. Each task should then find its local netmemory server, and call netmemory_cache on the local server with the netmemory object to obtain a local mach memory object corresponding to the netmemory object. The netmemory_cache call allows the netmemory servers to use more efficient and more distributed protocols for maintaining object consistency than the stan- dard memory manager interface. Finally, the resulting memory object should be given to vm_map to map the object into the caller's address space. gain, the netmemory object is only for use by netmemory_cache; it should not be handed directly to vm_map. The netmemory object can be explicitly destroyed by calling netmemory_destroy on the netmemory_control port. This call is not necessary on the current implementation of the net- memoryserver which cleans up a netmemory object after the last kernel has unmapped the object. The current netmemory server is actually a compatability front-end to the External Memory Manager server (see _x_m_m_s_e_r_v_e_r(_8) ). EXAMPLE The following is a routine which demonstrates how to use the netmemory server. /* * Create and map a shared object of given size with * netname "object_name". * * One task (the "master") should call this routine with * hostname = 0; the routine will then create a netmemory * object and register it with the netname server under the * supplied object name. All other tasks (the "slaves") call * this routine with the hostname where the master lives. */ kern_return_t map_object(object_name, hostname, address, size, anywhere) char *object_name; char *hostname; vm_offset_t *address; vm_size_t size; boolean_t anywhere; { kern_return_t kr; port_t netmemory_server; port_t memory_object; port_t netmemory_object; port_t netmemory_control; /* * Find the local netmemory server. * (If this routine is used a lot, this value can be cached.) */ kr = netname_look_up(name_server_port, "", "netmemoryserver", &netmemory_server); if (kr) { return kr; } /* * If a hostname is provided, then we are the slave and thus we * simply look up the netmemory object on the given host by using * the object name. * * If a hostname is not provided, then we are the master and thus * have the responsibility of creating a netmemory object and * registering it with the netname service under the given object * name. */ if (hostname) { kr = netname_look_up(name_server_port, hostname, object_name, &netmemory_object); if (kr) { return kr; } } else { kr = netmemory_create(netmemory_server, size, &netmemory_object, &netmemory_control); if (kr) { return kr; } kr = netname_check_in(name_server_port, object_name, PORT_NULL, netmemory_object); if (kr) { netmemory_destroy(netmemory_control); return kr; } } /* * Cache the object locally. Note that even the master must do this. */ kr = netmemory_cache(netmemory_server, netmemory_object, &memory_object); if (kr) { return kr; } /* * Map the object, either anywhere or at the supplied address. */ if (anywhere) { *address = 0; /* must be set */ } kr = vm_map(task_self(), address, size, 0, anywhere, memory_object, 0, FALSE, VM_PROT_DEFAULT, VM_PROT_DEFAULT, VM_INHERIT_SHARE); if (kr) { return kr; } return KERN_SUCCESS; } FILES DIAGNOSTICS NETMEMORY_SUCCESS operation succeeded. NETMEMORY_RESOURCE the server could not allocate the resources necessary to perform the operation. NETMEMORY_BAD_PARAMETER an invalid parameter was supplied. SEE ALSO _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) BUGS Older versions of the netmemoryserver tend to leak resources. HISTORY 30-Jun-88 Joseph S. Barrera (jsb) Created. 20-Feb-91 Joseph S. Barrera (jsb) Revised.