Table of Contents

Name

linx_hunt() - Search for a LINX endpoint matching a name

linx_hunt_from() - Search for a LINX endpoint matching a name and set another LINX endpoint to be the owner of the hunt.

Synopsis

#include <linx_types.h>
#include <linx.h>

int linx_hunt(LINX *linx, const char *name, union LINX_SIGNAL **hunt_sig);

int linx_hunt_from(LINX *linx, const char *name, union LINX_SIGNAL **hunt_sig, LINX_SPID from);

Description

linx_hunt() and linx_hunt_from() are used to search for a LINX endpoint matching the provided hunt name, usually in order to be able to obtain its spid and communicate with it. The hunt name may optionally be prepended by a path of link names to reach a remote node on which the endpoint shall be found. When the endpoint has been found, the provided signal hunt_sig is sent from the found endpoint to the calling endpoint. If no hunt signal (NULL) is provided, the default LINX hunt signal of type LINX_OS_HUNT_SIG is used. The call consumes the signal, taking ownership of the signal, and sets the hunt_sig pointer to LINX_NIL to prevent further access. The signal is consumed also if an error occurs.

If there are multiple endpoints with the same name, it is not specified which of these endpoints is used to resolve the hunt call. When the hunt signal is received, the linx_sender(3) call can be used to get the spid of the found endpoint. Note that the returned spid is always local even though it may correspond to a LINX endpoint on a remote node. LINX will transparently route signals to their intended destination endpoints on remote nodes when needed.

A pending hunt will be automatically cancelled if the linx endpoint that owns it is closed, e.g. if the caller exits. In the case with linx_hunt_from(), the from parameter indicates a different owner of the pending hunt. If the from endpoint is closed while the hunt is pending, the hunt will be freed. Note that from does NOT receive the hunt signal.

name is a null-terminated string that shall exactly match a LINX endpoints name. If the endpoint is located on a remote node, the name of a link to that node (or names in a sequence of links) shall be included as the leading part of the name according to the following syntax:
"[<link_1>/][<link_2>/]...[<link_N>/]name"
Example: "LinkToA/LinkToB/EndpointName" where a path of two links are passed to reach the LINX endpoint.

linx is the handle to the LINX endpoint that will receive the hunt signal.

hunt_sig is the signal which will be sent to the caller when the hunt has been resolved. The sender of the signal will be the matching LINX endpoint found. If hunt_sig is NULL, a default LINX hunt signal with signal number LINX_OS_HUNT_SIG will be sent instead. If hunt_sig is corrupt, abort(3) is called.

from specifies a different owner of a possible pending hunt. If the endpoint, with spid from, is closed, the pending hunt will be cancelled.

Return Value

Returns 0 if successful. -1 if an error occurred in which case errno is set.

Errors

ENOMEM Insufficient memory is available.

EBADF The linx handle refers to an invalid socket descriptor.

EFAULT The .I name parameter is invalid.

ECONNRESET The from spid in the linx_hunt_from(3) refers to a LINX endpoint that has been closed (i.e. in state LINX_ZOMBIE).

EPIPE This error is reported at an attempt to do a linx_hunt_from(3) and the from spid is a LINX endpoint that is being closed as the call occurs.

Bugs/Limitations

None.

Example

In this example client1 hunts for client2 and client3 */ 


Client 1:
#include <linx.h>
int
main (int argc, char *argv[]) 
{
  LINX *linx;
  LINX_SPID client2, client3;
  union LINX_SIGNAL *sig;
  const LINX_SIGSELECT sel_hunt_sig[] = { 1, LINX_OS_HUNT_SIG };
  /* Open a LINX endpoint with huntname "client1" */
  linx = linx_open("client1", NULL, 0);
  /* Hunt for client2 */
  linx_hunt(linx, "client2", NULL);
  /* Receive hunt signal */
  linx_receive(linx, &sig, sel_hunt_sig);
  /* Retrieve client2's spid */
  client2 = linx_sender(linx, &sig);
  /* Free the hunt signal */
  linx_free_buf(linx, &sig);
   /* Hunt for client3 */    
  linx_hunt(linx, "client3", NULL);
  /* Receive hunt signal */
  linx_receive(linx, &sig, sel_hunt_sig);
  /* Retrieve client3's spid */
  client3 = linx_sender(linx, &sig);
  /* Free the hunt signal */
  linx_free_buf(linx, &sig);
  /* Do work, e.g. exchanges signals with client2 or client3 ... */
  /* Close the LINX endpoint */
  linx_close(linx);
  return 0;
}
Client 2:
#include <linx.h>
int
main (int argc, char *argv[])
{
  LINX *linx;
  /* Open a LINX endpoint with huntname "client2" */
  linx = linx_open("client2", NULL, 0);
  /* Do work.... */
  /* When done close the LINX endpoint */
  linx_close(linx);
  /* "client2" can no longer be hunted on */
  return 0;
}
Client 3:
#include <linx.h>
int
main (int argc, char *argv[])
{
  LINX *linx;
  /* Open a LINX endpoint with huntname "client3" */
  linx = linx_open("client3", NULL, 0);
  /* Do work.... */
  /* When done close the LINX endpoint */
  linx_close(linx);
  /* "client3" can no longer be hunted on */
  return 0;
}

See Also

linx(7) , linx_attach(3) , linx_sender(3)

Author

Enea LINX team

Copyright

Copyright (c) 2006-2007, Enea Software AB All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of Enea Software AB nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Table of Contents