dmnet(3dm)
dmNet, dmNetIntro - Digital Media Network Library
As shipped in IRIX 6.5.7. Added in IRIX 6.5.5.
NAME dmNet, dmNetIntro - Digital Media Network Library SYNOPSIS #include <dmedia/dmnet.h> -ldmnet DMnetconnection cnp; DESCRIPTION dmNet Library is used by applications that need to transfer DMbuffers between processes on the same host, or on different hosts across a network. dmNet performs marshalling and unmarshalling of DMbuffers, converting timestamps and endianness. dmNet abstracts the underlying transport, and provides maximal throughput across network transports like Ethernet, Striped Hippi and Fibrechannel, by using native protocols whenever possible, thus liberating applications from the task of network-specific performance optimizations. dmNet also provides a low overhead local path for inter-process communication. dmNet is built upon a plugin architecture, allowing for extensible support of new transports by downloading plugins. PROGRAMMING MODEL dmNet uses a handle of type DMnetconnection to keep track of state associated with the dmnet connection. The library calls exported by dmnet are are modelled on BSD socket calls. dmNet supports unidirectional flow of DMbuffers; thus two connections must be made for bidirectional flow. PROGRAMMING INTERFACE Some calls are specific to sender or receiver, and are noted as such. All calls return DM_SUCCESS or DM_FAILURE. If DM_FAILURE is returned, a call to dmGetError(3dm) may be made to determine the cause of failure. dmNetOpen(3dm), dmNetClose(3dm) - initialize and close the handle, common to sender and receiver. dmNetListen(3dm), dmNetAccept(3dm) - receiver calls, must be called before dmNetConnect is called by sender. dmNetAccept blocks until dmNetConnect is called by sender. If dmNetListen fails with EADDRINUSE, a new port should be negotiated by the server and client. dmNetConnect(3dm) - sender call, must be called before dmNetAccept is called by receiver. dmNetSend(3dm) - sender call, sends a DMbuffer. dmNetRecv(3dm) - receiver call, receives a DMbuffer. dmNetRegisterPool(3dm), dmNetRegisterBuffer(3dm) - registers a DMbufferpool, or a single DMbuffer with dmNet. When dmNetRecv is called, a DMbuffer is allocated from the pool, or a preallocated DMbuffer is used to store the incoming DMbuffer. Registration needs to be done only by the receiver. dmNetRegisterBuffer indicates to dmNet that a preallocated DMbuffer is being passed into dmNetRecv. dmNetQueryHardware(3dm), dmNetQueryProtocol(3dm), dmNetSelectProtocol(3dm) - querying calls, used in conjunction with the configuration file /var/dmedia/dmnet/dmnet.conf. dmNetQueryHardware returns all network devices on the host; dmNetQueryProtocol returns all protocols supported by a particular network device; and dmNetSelectProtocol fills a DMparams structure with parameters necessary for dmNet to use a particular device and protocol. The configuration file contains lines of name=value pairs, and each line contains all the parameters and their values for a particular hardware and protocol. This frees application from having to set connection parameters explicitly, and allows it to present users with a choice of all hardware and protocol options available on the machine. The configuration file must be updated manually by a system adminstrator. dmNetGetParams(3dm) - called before the DMbufferpool is allocated so dmNet may modify or add parameters to the parameter list. dmNetDataFd(3dm) - returns a file descriptor that can be used with select, for non-blocking behaviour. EXAMPLE More complete examples are available in /usr/share/src/dmedia/dmnet. The following code fragment does not check return values, and is meant for illustration only. It sends or receives a single DMbuffer over tcp/ip, based on the flag "receiver". DMnetconnection cnp; DMbuffer dmbuf; DMparams* plist; short port=5555; dmNetOpen(&cnp); dmParamsCreate(&plist); dmParamsSetInt(plist, DMNET_PORT, port); if (receiver) { dmNetListen(cnp, plist); dmNetAccept(cnp, plist); } else { dmParamsSetString(plist, DMNET_REMOTE_HOSTNAME, "foo.sgi.com"); dmNetConnect(cnp, plist); } dmBufferSetPoolDefaults(plist, POOLSIZE, BUFFERSIZE, DM_TRUE, DM_FALSE); dmNetGetParams(cnp, plist); dmBufferCreatePool(plist, &pool); dmNetRegisterPool(cnp, pool); if (receiver) { dmNetRecv(cnp, &dmbuf); /* do cool stuff with the buffer we've received */ } else { dmBufferAllocate(pool, &dmbuf); /* fill the dmbuf with data */ dmNetSend(cnp, dmbuf); } dmBufferFree(dmbuf); dmNetClose(cnp); PARAMETERS DMNET_CONNECTION_TYPE specifies the transport to use, and is one of DMNET_LOCAL, DMNET_TCP, DMNET_STRIPED_HIPPI, DMNET_PLUGIN (default is DMNET_TCP). DMNET_LOCAL is the fast local case, when DMbuffers are transferred between processes. DMNET_TCP works over all networks that implement TCP/IP, including Ethernet, Hippi, Fibrechannel, ATM, etc. Note that TCP will not yield the best performance in the general case, so native protocols are supported for maximum throughput (wire speeds for most configurations) over Hippi and Fibrechannel. DMNET_STRIPED_HIPPI uses the native Hippi Framing Protocol, also referred to as the character driver interface. The sender and receiver open Hippi devices, like /dev/hippi0, for instance, perform a few ioctls, and make read and write calls. Thus the hippi device(s) must be specified to dmNet through parameters DMNET_HIPPI_DEV#, where # is 0, 1, 2,..,n, where n is specified by DMNET_HIPPI_NDEV. When multiple hippi devices are specified, data is striped across all specified devices with almost a linear increase in throughput with number of devices (a single fibre should yield over 80 MB/sec of throughput). So for example, if the host has active hippi devices /dev/hippi3 and /dev/hippi5, you would set DMNET_HIPPI_NDEV to 2, DMNET_HIPPI_DEV0 to "/dev/hippi3" and DMNET_HIPPI_DEV1 to "/dev/hippi5". netstat -i reveals all active hippi devices. The example code in /usr/share/src/dmedia/dmnet/ demonstrates how this may be done in more detail. Note that striping is possible because of multiple threads, and sproc is called from within dmNet when this connection type is set. Hippi works best with very large buffers, in the order of MBytes. Small buffer transfers will not give high throughput. DMNET_PLUGIN specifies that a plugin will be used, and DMNET_PLUGIN_NAME indicates the name of the plugin. dmNet is based on a plugin architecture, which means that plugins are available for download that support new interfaces. The Fibrechannel Transporter interface is an example of a network transport that is supported through plugins. Hippi is another example, though hippi is also integrated with the dmNet core. The plugins are usually located in /usr/lib32/dmedia/plugins/dmnet/. Plugins may require additional parameters, and these are specified in their header files, located at /usr/include/dmnet/. Fibrechannel transporter, for example, requires the specification of DMNET_TRANSPORTER_REMOTE_HOSTNAME. DMNET_PORT is the port agreed upon by the sender and receiver. This must be specified, even if the data transport is not tcp, because there is always some control tcp traffic. Note that this means that there must always be a tcp path between hosts using dmNet. Port negotiation is assumed to take place by external means, such as through an independant network connection, or with a well known port, etc. If dmNetListen fails with EADDRINUSE, the port specified is being used, and another one must be chosen. DMNET_REMOTE_HOSTNAME must be specified before dmNetConnect can be called (unless DMNET_REMOTE_SOCKADDR is specified). The hostname must be the address of a network interface that supports tcp/ip. DMNET_REMOTE_SOCKADDR , DMNET_LOCAL_SOCKADDR These are optional and provide a way for the application to specify a socket address. DMNET_REMOTE_SOCKADDR is specified before dmNetConnet, and DMNET_LOCAL_SOCKADDR is specified before dmNetAccept. If DMNET_REMOTE_HOSTNAME is specified, DMNET_REMOTE_SOCKADDR is ignored. DMNET_LOCAL_SOCKADDR may be used to specify the interface to bind to if the host has multiple interfaces. FILES /usr/lib32/libdmnet.so dmNet DSO /usr/include/dmedia/dmnet.h dmNet call prototypes /usr/include/dmedia/dmnet_params.h dmNet param defns /usr/include/dmnet/ header files for plugins /usr/lib32/dmedia/plugins/dmnet/ plugin DSOs /var/dmedia/dmnet/dmnet.conf configuration file for querying SEE ALSO dmNetOpen(3dm), dmNetClose(3dm), dmNetListen(3dm), dmNetAccept(3dm), dmNetConnect(3dm), dmNetSend(3dm), dmNetRecv(3dm), dmNetQueryHardware(3dm), dmNetQueryProtocol(3dm), dmNetSelectProtocol(3dm), dmNetRegisterPool(3dm), dmNetRegisterBuffer(3dm), dmNetGetParams(3dm), dmNetDataFd(3dm), DMbuffer(3dm), vlintro(3dm)