dnxJobList.c File Reference

Implements the DNX Job List mechanism. More...

#include "dnxJobList.h"
#include "dnxError.h"
#include "dnxDebug.h"
#include "dnxLogging.h"
#include "dnxTimer.h"
#include <sys/time.h>

Go to the source code of this file.

Data Structures

struct iDnxJobList_

The JobList implementation data structure. More...

Defines

#define DNX_JOBLIST_TIMEOUT 5

#define DNX_TIMER_SLEEP 5000

Typedefs

typedef struct iDnxJobList_ iDnxJobList

The JobList implementation data structure.

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.

Variables

DnxJobList * joblist

Detailed Description

Implements 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.c.

Define Documentation

#define DNX_JOBLIST_TIMEOUT 5

Wake up to see if we're shutting down.

Definition at line 37 of file dnxJobList.c.

#define DNX_TIMER_SLEEP 5000

Timer sleep interval, in milliseconds

Definition at line 38 of file dnxJobList.c.

Typedef Documentation

typedef struct iDnxJobList_ iDnxJobList

The JobList implementation data structure.

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 60 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.

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 249 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.

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 296 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.

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 336 of file dnxJobList.c.

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

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 187 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.

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 126 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.

Variable Documentation

DnxJobList* joblist

Definition at line 40 of file dnxJobList.c.


Data Structures
struct	iDnxJobList_
	The JobList implementation data structure. More...
Defines
#define	DNX_JOBLIST_TIMEOUT 5
#define	DNX_TIMER_SLEEP 5000
Typedefs
typedef struct iDnxJobList_	iDnxJobList
	The JobList implementation data structure.
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.
Variables
DnxJobList *	joblist