
% Template for a simple journal or conference style article

\documentstyle[12pt,fullpage]{article}
\begin{document}
\pagestyle{plain}
\title{\bf CIS 631: Project Design Documentation\\ \ \\ Implementation of Farming Under PVM}
\author {Sameer S. Shende}
\maketitle
\vspace*{.3in}

\section*{API Definition}

To implement farming under pvm, an additional daemon (pvmfarmd) will have to be spawned off. This will maintain information regarding farm names, worker class names, packet information, and will enroll worker tasks into a worker class. In the documentation that follows this daemon (pvmfarmd) will be referred to as server and a process requesting some service will be denoted as client. The API for farming is described below :
\subsection*{At the farmer end}
\begin{enumerate}
\item
{\bf int 	pvm\_farm\_init (char *farm\_name); }

The routine pvm\_farm\_init() creates a process farm with a name specified by the 
argument {\em farm\_name}. In an application, the farm name is unique (i.e., the 
user should not invoke this routine twice with the same name). Multiple farms 
can be used with a separate farm names. This name is used by the worker task to enroll in a farm.
	Returns OK or ERROR.
\begin{verbatim}
	e.g.,
	pvm_farm_init("Farmer1");
\end{verbatim}
\item
{\bf int pvm\_get\_worker\_class\_id (char *farm\_name, char *worker\_class\_name); }

The routine pvm\_get\_worker\_class\_id() returns the identifier that 
represents a worker class named {\em worker\_class\_name} associated 
with the farmer named {\em farm\_name}.  This is used by the farmer to uniquely
identify a particular worker class, to send work packets and receive reply 
packets. Returns ERROR on error or a positive integer {\em id}. This identifier
is used by subsequent farmer calls to send data packets to this worker class or
 to receive replies from the worker class.
\begin{samepage}
\begin{verbatim}
	e.g.,
	id = pvm_get_worker_class_id("Farmer1", "WC1");
	if (id == ERROR)
	{
		printf("Error in getting worker class id\n");
		pvm_exit();
		exit(1);
	}
\end{verbatim}
\end{samepage}
\item
{\bf int	pvm\_send\_work\_packet(int id); 	 }

The routine pvm\_send\_work\_packet() sends the message to one worker task associated with the 
worker class whose identifier is specified by id. The data should be packed in
a buffer (the active send buffer) created by pvm\_initsend() or pvm\_mkbuf();
PvmDataDefault is used to create the buffer so that XDR encoding can be done
for communication between dissimilar hosts (little endian and big endian hosts).
	Returns OK or ERROR.
\begin{verbatim}
	e.g.,
	int id, data, bufid; 
	id = pvm_get_worker_class_id("Farmer1","WC1");
	bufid = pvm_mkbuf(PvmDataDefault); /* pvm call creates buffer */
	pvm_setsbuf(bufid); /* sets this as the active send buffer
		This is also the default action taken */
	data = 500; /* gets data ready for packing in the buffer */
	pvm_pkint(&data, 1, 1); /* packs one int data item, stride = 1 */
	/* calls to pack the data */
	pvm_send_work_packet(id, 34);
	pvm_freebuf(bufid); /* frees the buffer */
\end{verbatim}

\item 
{\bf int	bufid = pvm\_recv\_reply\_packet(id); }

This blocking receive reply packet routine will wait until has arrived from the
worker class specified by the identifier {\em id}.  This call 
places the message in a new active receive buffer that is created. The previous
active receive buffer is cleared unless it has been saved with a pvm\_setrbuf() call.
\begin{verbatim}
	e.g.,	
	pvm_recv_reply_packet(id);
\end{verbatim}

\item 
{\bf int	pvm\_farm\_terminate(char *farm\_name); }
	
This routine shuts down a farm and frees the worker classes associated with the farm whose name is specified by {\em farm\_name}.
The tasks waiting on a receive are sent a message that the farm has terminated.
Returns OK or ERROR.
\begin{verbatim}
	e.g.,
	pvm_farm_terminate("Farmer1");
\end{verbatim}

\item 
{\bf int	pvm\_start\_farmd(void); }

This routine starts the pvmfarmd daemon which is responsible for farming 
related calls. This daemon can be started manually from the pvm shell or by
using this call. This should be called only once in the entire application.
Returns OK or ERROR.
\begin{verbatim}
	e.g.,
	pvm_start_farmd(); /* starts the daemon.*/
\end{verbatim}
\item 
{\bf  int	pvm\_stop\_farmd(void); }

This routine sends a message to the pvmfarmd to terminate itself. This should
also be called by only one task in the application. This should be done by the
farmer task after it has terminated the farm.
Returns OK or ERROR.
\begin{verbatim}
	e.g.,
	pvm_stops_farmd(); /* stops the daemon.*/
\end{verbatim}

	
\subsection*{At the worker end}
\item 
{\bf int	pvm\_init\_worker\_class(char *farm\_name, char *worker\_class\_name); }

The pvm\_init\_worker\_class() routine creates (if it doesn't exist) a worker class
named {\em worker\_class\_name} and enrolls the calling task in the worker class.
This worker class is associated with the farmer task specified by {\em farm\_name}. This call blocks till a farm is created (in case the farmer has not created the farm).
	Returns OK or ERROR.
\begin{verbatim}
	e.g.,
	pvm_init_worker_class("Farmer1", "WC1");
\end{verbatim}
\item
{\bf int	bufid = pvm\_recv\_work\_packet(void);  }

This blocking routine will wait until a message arrivs from the farmer task.A 
worker task can be associated with at most one farmer (and a worker class)  at
a time. The previous active receive buffer is cleared unless it has been 
saved with a pvm\_setrbuf() call. This call returns bufid or PvmFarmTerminated
if the farmer has executed a farm\_terminate() call in which case the worker is
free to do any other activity not associated with the current farm.
\begin{verbatim}
	e.g.,
	buffer_id = pvm_recv_reply_packet();
	/* All unpacking routines */
\end{verbatim}

\item 
{\bf int	pvm\_send\_reply\_packet(void); }

	This routine sends a reply packet which has been packed into the 
active send buffer, to the farmer task.
	Returns OK or ERROR.
\begin{verbatim}
	e.g.,
	/* initialise the buffer for sending */
	int bufid,data;
	bufid = pvm_mkbuf(PvmDataDefault); /* makes a new buffer */
	pvm_setsbuf(bufid); /* done by default - sets this 
		as the active send buffer used by pvm_send_reply_packet() */
	data = 5; /* some reply packet */
	pvm_pkint(&data, 1, 1); /* packs the integer into the buffer */
	pvm_send_reply_packet(); /* sends the buffer to the farmer */
	pvm_freebuf(bufid);
\end{verbatim}
\item 
{\bf int	pvm\_leave\_farm(void); }

	This routine is called by the worker task to disassociate itself from
the farm in which it is currently enrolled. This call removes the task related
information of this task from the worker class information repository maintained
by the central pvmfarmd daemon (farm daemon). After this call is executed, the
calling worker task no longer receives work packets from the farmer. The worker
can enroll in any farm subsequently, by calling the pvm\_init\_worker\_class()
routine. This allows for the worker process to migrate from one farm to another
dynamically at runtime.  
	Returns OK or ERROR.
\begin{verbatim}
	e.g.,
	pvm_leave_farm(); /* leaves the farm */
\end{verbatim}
	
\end{enumerate}

\end{document}

% ------------ end of document ----------------------

% here are some templates of different environments you can cut and paste:

\begin{figure}
\vspace{3in}
\caption{}
\end{figure}

\begin{itemize}
\item
...
\end{itemize}

\begin{enumerate}
\item
...
\end{enumerate}

