Section index Manual top page Document Top page

pmx

PMX High-Performance Communication Library for Cluster Computing. More...

Files
file	pm.h
char *	pmxErrorString (int error)
int	pmxGetAttribute (pmContext *pmc, pmAttribute *attrp)
int	pmxOpen (pm_key_t key, pm_flags_t flags, pmContext **pmcp, int *fdp)
int	pmxIsReady (pmContext *pmc)
int	pmxReset (pmContext *pmc)
int	pmxInitialize (pmContext *pmc)
int	pmxStart (pmContext *pmc)
int	pmxGetMtu (pmContext *pmc, pm_node_t nodeno, pm_size_t *tsmtup, pm_size_t *osmtup)
int	pmxNotCommunicating (pmContext *pmc)
int	pmxStop (pmContext *pmc)
int	pmxClose (pmContext *pmc)
void	pmxDescribeRouting (pmContext *pmc, FILE *fp)
void	pmxDump (pmContext *pmc, FILE *fp)
void	score_become_busy (void)
int	pmxReleaseReceiveBuffer (pmContext *pmc, pm_desc_t desc)
int	pmxGetSendBuffer (pmContext *pmc, pm_node_t nodeno, void **bufp, pm_size_t len, pm_desc_t *descp)
int	pmxSend (pmContext *pmc, pm_desc_t desc)
int	pmxTruncateBuffer (pmContext *pmc, pm_desc_t desc, pm_size_t len)
int	pmxKeepSendDesc (pmContext *pmc, pm_desc_t desc)
int	pmxGetSendDescInfo (pmContext *pmc, pm_desc_t desc, pmSendDescInfo *infop)
int	pmxReleaseSendDesc (pmContext *pmc, pm_desc_t desc)
int	pmxIsSendDone (pmContext *pmc, pm_desc_t desc)
int	pmxBeforeSelect (pmContext *pmc, fd_set *fdsp, int *fdmaxp, sigset_t *maskp)
int	pmxAfterSelect (pmContext *pmc)
int	pmxBreak (pmContext *pmc)
int	pmxWaive (pmContext *pmc)
int	pmxContinue (pmContext *pmc)
int	pmxExport (pmContext *pmc, void *addr, pm_size_t len, pm_node_t dst, pmAddrHandle *hndlp)
int	pmxUnexport (pmContext *pmc, pmAddrHandle *hndlp)
int	pmxWrite (pmContext *pmc, pmAddrHandle *locp, pm_off_t loff, pmAddrHandle *remp, pm_off_t roff, pm_size_t length, pm_desc_t *descp)
int	pmxIsWriteDone (pmContext *pmc, pm_desc_t desc)
int	pmxRead (pmContext *pmc, pmAddrHandle *remp, pm_off_t roff, pmAddrHandle *locp, pm_off_t loff, pm_size_t length, pm_desc_t *descp)
int	pmxIsReadDone (pmContext *pmc, pm_desc_t desc)
int	pmxSave (pmContext *pmc, void **savep)
int	pmxReopen (pmContext *pmc, void *save)
int	pmxAddMember (pmContext *pmc, const char *netname)

---

Detailed Description

PMX High-Performance Communication Library for Cluster Computing.

PMX is a high-performance communication library supporting multiple networks, such as Myrinet(TM), Infiniband, Ethernet, shared-memory, and any combination of those networks. PMX is also designed so that checkpoint/restart and gang-scheduling can be implemented with.

---

Function Documentation

int pmxAddMember	(	pmContext *	pmc,
		const char *	netname
	)

The pmxAddMember() function adds member device to PMX context.

Parameters:

[in]	pmc	PMX context
[in]	netname	network name defined in the scorehosts.db(5) file.

Returns:

zero is returned if the function succeeds.

Return values:

ENOENT

No such PMX device having the name of netname

See also:

pmxIsReady().

int pmxAfterSelect

(

pmContext *

pmc

)

This function must be called after calling (p)select() system call for blocking message receive. The (p)select() system call should be wrapped with the pair of calling pmxBeforeSelect() and pmxAfterSelect() functions.

Parameters:

[in]

pmc

PMX context

Returns:

return zero if the function succeeds.

See also:

pmxBeforeSelect()

int pmxBeforeSelect	(	pmContext *	pmc,
		fd_set *	fdsp,
		int *	fdmaxp,
		sigset_t *	maskp
	)

This function must be called before calling the (p)select() system call for blocking message receive. The (p)select() system call should be wrapped with the pair of calling pmxBeforeSelect() and pmxAfterSelect() functions.

Parameters:

[in]	pmc	PMX context
[in,out]	fdsp	Pointer to the fdset to be passed to the (p)select() system call
[in,out]	fdmaxp	Pointer to the max number of file descriptor in the fdset
[in,out]	maskp	Pointer ot the signal mask to be passed to the pselect system call

Returns:

Zero is returned if the function succeeds.

Return values:

	EPERM	At least one member context have the capability of blocking receive.
	others	An error number returning from member context.

See also:

pmxAfterSelect()

int pmxClose

(

pmContext *

pmc

)

The pmxClose() function finalizes the endpoint function of the context and then frees all allocated resources.

Parameters:

[in]

pmc

PMX context

Returns:

zero is returned if the function succeeds.

void pmxDump	(	pmContext *	pmc,
		FILE *	fp
	)

The pmxDump() function dumps the content of PMX context in a human-readable format for debugging.

Parameters:

[in]	pmc	PMX context
[in]	fp	pointer to a valid FILE stream

int pmxGetAttribute	(	pmContext *	pmc,
		pmAttribute *	attrp
	)

The pmxGetAttribute() function is to obtain attributes of PMX context.

Parameters:

[in]	pmc	PMX context
[out]	attrp	Pointer to pmAttribute structure

Returns:

Zero is returned if the function succeeds.

Return values:

EINVAL

pmc is NULL or attrp is NULL

int pmxGetSendBuffer	(	pmContext *	pmc,
		pm_node_t	nodeno,
		void **	bufp,
		pm_size_t	len,
		pm_desc_t *	descp
	)

The pmxGetSendBuffer() function is to allocate a buffer for message sending. When the message to be sent is ready to send, call the pmxSend() function. The function calls of pmxGetSendBuffer() and pmxSend() must be paired always.

Parameters:

[in]	pmc	PMX context
[in]	nodeno	Destination node
[out]	bufp	Handle to the allocated send buffer
[in]	len	Length of sending message
[out]	descp	Pointer to a PMX send descriptor

Returns:

zero is returned if the function succeeds.

Return values:

	ENOBUFS	no buffer is available
	EBUSY	no resource is available temporarily
	E2BIG	nodeno is too big
	EMSGSIZE	message length is larger than MTU
	EPERM	try to send itself
	EINVAL	buffer handle is NULL or message length is zero

See also:

pmxSend()

int pmxGetSendDescInfo	(	pmContext *	pmc,
		pm_desc_t	desc,
		pmSendDescInfo *	infop
	)

The pmxGetSendDescInfo() function is to obtain the status and send descriptor. The descriptor information is stored into the pmSendDescInfo structure.

Parameters:

[in]	pmx	PMX ocntext
[in]	desc	PMX send descriptor
[out]	infop	pointer to the pmSendDescInfo structure

Returns:

zero is returned if the function succeeds.

Return values:

EINVAL

desc does not look like a right PMX send descriptor

See also:

pmxGetSendBuffer(), pmxKeepSendDesc()

int pmxIsReady

(

pmContext *

pmc

)

The pmxIsReady() function succeeds when there are enough member PMX devices are added by calling the pmxAddMember() function and the context can communicate with every other node except self node.

Parameters:

[in]

pmc

PMX context

Returns:

zero is returned if the function succeeds.

Return values:

EBUSY

Not yet to have enough member devices.

See also:

pmxAddMember().

int pmxIsSendDone	(	pmContext *	pmc,
		pm_desc_t	desc
	)

The pmxIsSendDone() function succeeds when the sent message arrives at the destination node. Otherwise it returns EBUSY. When the send descriptor is PMX_DESC_ANY, then the pmxIsSendDone() function succeeds when all of the sent messages arrives.

Parameters:

[in]	pmc	PMX context
[in]	desc	PMX send descriptor

Returns:

zero is returned if the function succeeds.

Return values:

EINVAL

desc does not look like a right PMX send descriptor

See also:

pmxSend()

int pmxKeepSendDesc	(	pmContext *	pmc,
		pm_desc_t	desc
	)

The pmxKeedSendDesc() function is not to discard the send descriptor after calling the pmxSend() function. The send message buffer allocated by calling the pmxGetSendBuffer() function is also accessible after calling the pmxSend() function, untile the descriptor is freed by calling the pmxReleaseSendDesc() function.

Parameters:

[in]	pmc	PMX context
[in]	desc	PMX send descriptor

Returns:

zero is returned if the function succeeds.

Return values:

EINVAL

desc does not look like a right PMX send descriptor

See also:

pmxGetSendBuffer(), pmxKeepSendDesc()

int pmxNotCommunicating

(

pmContext *

pmc

)

The pmxNotCommunicating() function succeeds when there is NO outstanding messages to send nor receive.

Parameters:

[in]

pmc

PMX context

Returns:

zero is returned if the function succeeds.

Return values:

EBUSY

one or more outstanding messages exist

int pmxReleaseReceiveBuffer	(	pmContext *	pmc,
		pm_desc_t	desc
	)

The pmxReleaseReceiveBuffer() released the buffer region of a received message. The received message region should not be accessed after calling this function. Ifhen the value of the receive descriptor is PMX_DESC_ANY, then all received messages are freed.

Parameters:

[in]	pmc	PMX context
[in]	desc	PMX receive descriptor

Returns:

zero is returned if the function succeeds.

Return values:

	EINVAL	handle is NULL
	EINVAL	desc does not look like a right PMX receive descriptor

See also:

pmxReleaseReceiveBuffer()

int pmxReleaseSendDesc	(	pmContext *	pmc,
		pm_desc_t	desc
	)

The pmxReleaseSendDesc() function is to free the send descriptor kept by calling the pmxKeepSendDesc() function.

Parameters:

[in]	pmc	PMX context
[in]	desc	PMX send descriptor

Returns:

zero is returned if the function succeeds.

Return values:

EINVAL

desc does not look like a right PMX send descriptor

See also:

pmxGetSendBuffer(), pmxKeepSendDesc()

int pmxSave	(	pmContext *	pmc,
		void **	savep
	)

The pmxSave() function allocates a memory region and saves the internal information to the allocated region, so that the calling process can have a checkpoint.

Parameters:

[in]	pmc	PMX context
[out]	savep	allocated memory region for save

Returns:

zero is returned if the function succeeds.

Return values:

ENOMEM

Not enough memory to allcoate the save region

See also:

pmxReopen().

int pmxSend	(	pmContext *	pmc,
		pm_desc_t	desc
	)

The pmxSend() function is to send a message. If the desc is not kept by calling the pmxKeepSendDesc() function, then the send descriptor is freed and prohibited to access. When the send descriptor is the value of PMX_DESC_ANY, then all sending messages will be sent.

Parameters:

[in]	pmc	PMX context
[in]	desc	PMX send descriptor

Returns:

zero is returned if the function succeeds.

Return values:

EINVAL

desc does not look like a right PMX send descriptor

See also:

pmxGetSendBuffer(), pmxKeepSendDesc()

int pmxTruncateBuffer	(	pmContext *	pmc,
		pm_desc_t	desc,
		pm_size_t	len
	)

The pmxTruncateBuffrer() function is to shorten the message size specified in the argument of the pmxGetSendBuffer() function.

Parameters:

[in]	pmc	PMX context
[in]	desc	PMX send descriptor
[in]	len	length of send message to be truncated

Returns:

zero is returned if the function succeeds.

Return values:

EINVAL

desc does not look like a right PMX send descriptor

See also:

pmxGetSendBuffer()

---

CREDIT

This document is a part of the SCore cluster system software developed at PC Cluster Consortium, Japan. Copyright (C) 2003-2008 PC Cluster Consortium.