dnxJobList.h File Reference

Definitions and prototypes for the DNX Job List mechanism. More...

#include <time.h>
#include "dnxProtocol.h"

Go to the source code of this file.

Data Structures
struct	DnxNewJob
	A structure to manage new jobs dispatched to nodes. More...
struct	DnxJobList
	An abstract data type for a DNX Job List object. More...
Functions
int	dnxJobListAdd (DnxJobList *pJobList, DnxNewJob *pJob)
	Add a job to a job list.
int	dnxJobListExpire (DnxJobList *pJobList, DnxNewJob *pExpiredJobs, int *totalJobs)
	Expire a set of old jobs from a job list.
int	dnxJobListDispatch (DnxJobList *pJobList, DnxNewJob *pJob)
	Select a dispatchable job from a job list.
int	dnxJobListCollect (DnxJobList *pJobList, DnxXID *pxid, DnxNewJob *pJob)
	Locate a pending job to which collected results should apply.
int	dnxJobListCreate (unsigned size, DnxJobList **ppJobList)
	Create a new job list.
void	dnxJobListDestroy (DnxJobList *pJobList)
	Destroy a job list.

---

Detailed Description

Definitions and prototypes for the DNX Job List mechanism.

Author:

Robert W. Ingraham (dnx-devel@lists.sourceforge.net)

Attention:

Please submit patches to http://dnx.sourceforge.net

Definition in file dnxJobList.h.

---

Function Documentation

int dnxJobListAdd	(	DnxJobList *	pJobList,
		DnxNewJob *	pJob
	)

Add a job to a job list.

This routine is invoked by the DNX NEB module's Service Check handler to add new service check requests (i.e., a "job") to the Job List.

Jobs are marked as Waiting to be dispatched to worker nodes (via the Dispatcher thread.)

Parameters:

[in]	pJobList	- the job list to which pJob should be added.
[in]	pJob	- the job to be added to pJobList.

Returns:

Zero on success, or a non-zero error value.

Definition at line 59 of file dnxJobList.c.

References DnxNewJob::cmd, iDnxJobList_::cond, iDnxJobList_::dhead, DNX_ERR_CAPACITY, DNX_JOB_PENDING, DNX_OK, DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, dnxDebug(), dnxLog(), iDnxJobList_::head, iDnxJobList_::list, iDnxJobList_::mut, DnxXID::objSerial, DnxXID::objSlot, iDnxJobList_::size, DnxNewJob::state, iDnxJobList_::tail, and DnxNewJob::xid.

Referenced by dnxPostNewJob().

int dnxJobListCollect	(	DnxJobList *	pJobList,
		DnxXID *	pxid,
		DnxNewJob *	pJob
	)

Locate a pending job to which collected results should apply.

This routine is invoked by the Collector thread to dequeue a job from the Job List when its service check result has been posted by a worker node.

The job *is* removed from the the Job List.

Parameters:

[in]	pJobList	- the job list from which to obtain the pending job.
[in]	pxid	- the unique identifier for this pending job.
[out]	pJob	- the address of storage in which to return collected result information about the job belonging to pxid.

Returns:

Zero on success, or a non-zero error value.

Definition at line 230 of file dnxJobList.c.

References iDnxJobList_::dhead, DNX_ERR_INVALID, DNX_ERR_NOTFOUND, DNX_JOB_COMPLETE, DNX_JOB_NULL, DNX_OK, DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, dnxDebug(), dnxEqualXIDs(), iDnxJobList_::head, iDnxJobList_::list, iDnxJobList_::mut, DnxXID::objSerial, DnxXID::objSlot, iDnxJobList_::size, DnxNewJob::state, iDnxJobList_::tail, and DnxNewJob::xid.

Referenced by dnxCollector().

int dnxJobListCreate	(	unsigned	size,
		DnxJobList **	ppJobList
	)

Create a new job list.

This routine is invoked by the DNX NEB module's initialization routine to create the DNX Job List.

The Job List contains a time-ordered list of service check requests (i.e., "jobs") that are either waiting to be dispatched to a worker node for execution (state = Waiting) or are already executing on a worker node and are pending the service check result from the worker node (state = Pending).

Parameters:

[in]	size	- the initial size of the job list to be created.
[out]	ppJobList	- the address of storage for returning a new job list object pointer.

Returns:

Zero on success, or a non-zero error value.

Definition at line 276 of file dnxJobList.c.

References iDnxJobList_::cond, DNX_ERR_MEMORY, DNX_OK, DNX_PT_COND_DESTROY, DNX_PT_MUTEX_DESTROY, DNX_PT_MUTEX_INIT, DNX_TIMER_SLEEP, dnxTimerCreate(), iDnxJobList_::list, iDnxJobList_::mut, iDnxJobList_::size, xfree, and xmalloc.

Referenced by dnxServerInit().

void dnxJobListDestroy

(

DnxJobList *

pJobList

)

Destroy a job list.

This routine is invoked by the DNX NEB module's de-initialization routine to release and remove the DNX Job List.

Parameters:

[in]

pJobList

- refers to the job list to be destroyed.

Definition at line 316 of file dnxJobList.c.

References iDnxJobList_::cond, DNX_PT_COND_DESTROY, DNX_PT_MUTEX_DESTROY, dnxTimerDestroy(), iDnxJobList_::list, iDnxJobList_::mut, iDnxJobList_::timer, and xfree.

Referenced by dnxServerDeInit().

int dnxJobListDispatch	(	DnxJobList *	pJobList,
		DnxNewJob *	pJob
	)

Select a dispatchable job from a job list.

This routine is invoked by the Dispatcher thread to select the next job waiting to be dispatched to a worker node.

The job is *not* removed from the Job List, but is marked as InProgress; that is, it is waiting for the results from the service check.

Parameters:

[in]	pJobList	- the job list from which to select a dispatchable job.
[out]	pJob	- the address of storage in which to return data about the job to be dispatched. Makes a copy of the job in the job list and stores the copy in the pJob parameter.

Returns:

Zero on success, or a non-zero error value.

Todo:

Need to track total number of Pending jobs in the JobList structure? OR simply check to see if the dhead index points to a valid Pending job?

Definition at line 169 of file dnxJobList.c.

References iDnxJobList_::cond, iDnxJobList_::dhead, DNX_JOB_INPROGRESS, DNX_JOB_PENDING, DNX_JOBLIST_TIMEOUT, DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, dnxDebug(), iDnxJobList_::head, iDnxJobList_::list, iDnxJobList_::mut, DnxXID::objSerial, DnxXID::objSlot, iDnxJobList_::size, DnxNewJob::state, iDnxJobList_::tail, and DnxNewJob::xid.

Referenced by dnxDispatcher().

int dnxJobListExpire	(	DnxJobList *	pJobList,
		DnxNewJob *	pExpiredJobs,
		int *	totalJobs
	)

Expire a set of old jobs from a job list.

This routine is invoked by the Timer thread to dequeue all jobs whose timeout has occurred.

Note that this routine walks the *entire* Job List and can remove jobs that are either InProgress (awaiting a result) or Pending (awaiting dispatch.)

Jobs that are deemed to have expired are passed to the Timer thread via a call back mechanism (for efficiency.)

Parameters:

[in]	pJobList	- the job list from which to expire old jobs.
[out]	pExpiredJobs	- the address of storage in which to return a list of up to totalJobs jobs.
[in,out]	totalJobs	- on entry, contains the maximum size of the array pointed to by pExpiredJobs; on exit, contains the number of jobs stored in the pExpiredJobs array.

Returns:

Zero on success, or a non-zero error value. (Currently always returns zero.)

Note:

This routine is called from dnxTimer, which is a deferred cancellation thread start procedure. If new code is added in the future, which calls any pthread or system cancellation points then appropriate cleanup routines should be pushed as well. As it currently stands, the only place we could be cancelled is while waiting for the list mutex. If we are cancelled during this time, no resources will be lost.

Definition at line 108 of file dnxJobList.c.

References iDnxJobList_::dhead, DNX_JOB_INPROGRESS, DNX_JOB_NULL, DNX_JOB_PENDING, DNX_OK, DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, DnxNewJob::expires, iDnxJobList_::head, iDnxJobList_::list, iDnxJobList_::mut, iDnxJobList_::size, DnxNewJob::state, and iDnxJobList_::tail.

Referenced by dnxTimer().