Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Follow the PBS Pro Design Document Guidelines.
Link to discussion on Developer Forum: <http://community.pbspro.org/t/design-for-refactoring-pbs-database-code/2009>
Link to issue: <issue link if available>
Link to pull request: <PR link if available>

For easy maintainability, current database-related code within the PBS server needs to be refactored into a separate pluggable dynamic library. And this design page discusses the APIs using which PBS server can talk to Libdb, the database dynamic library using which PBS can talk to the database. Another motivation behind this refactoring is the added advantage of moving to any database without having to do major code changes within PBS itself.

1.1. Files: List of files PBS will need to have database support.

PBS_EXEC/lib/libdb.so

Description: This dynamic library will have the functionality for the PBS server to access the database.

...

Code Block
struct pbs_db_obj_info {
  int 	pbs_db_obj_type; /* identifies the contained object type */
  union {
	pbs_db_job_info_t	*pbs_db_job; 	/* map database job structure to C */
	pbs_db_jobscr_info_t	*pbs_db_jobscr;	/* map database job script to C */
	pbs_db_resv_info_t	*pbs_db_resv;	/* map database resv structure to C */
	pbs_db_svr_info_t	*pbs_db_svr;	/* map database server structure to C */
	pbs_db_que_info_t	*pbs_db_que;	/* map database queue structure to C */
	pbs_db_node_info_t	*pbs_db_node;	/* map database node structure to C */
	pbs_db_sched_info_t	*pbs_db_sched;	/* map database scheduler structure to C */	
	pbs_db_mominfo_time_t	*pbs_db_mominfo_tm; /* map database mominfo_time structure to C */
  } pbs_db_un;
};
typedef struct pbs_db_obj_info pbs_db_obj_info_t;

/* Structure used to map database job structure to C */
struct pbs_db_job_info {
	char     ji_jobid[PBS_MAXSVRJOBID + 1]; /* job identifier */
	INTEGER  ji_state; 	/* INTEGERernalInternal copy of state */
	INTEGER  ji_substate; 	/* job sub-state */
	INTEGER  ji_svrflags; 	/* server flags */
	INTEGER  ji_numattr; 	/* not used */
	INTEGER  ji_ordering; 	/* special scheduling ordering */
	INTEGER  ji_priority; 	/* INTEGERernal priority */
	BIGINT   ji_stime; 	/* time job started execution */
	BIGINT   ji_endtBdry; 	/* estimate upper bound on end time */
	char     ji_queue[PBS_MAXQUEUENAME + 1]; /* name of current queue */
	char     ji_destin[PBS_MAXROUTEDEST + 1]; /* dest from qmove/route */
	INTEGER  ji_un_type; 	/* job's queue type */
	INTEGER  ji_momaddr; 	/* host addr of Server */
	INTEGER  ji_momport; 	/* port # */
	INTEGER  ji_exitstat; 	/* job exit status from MOM */
	BIGINT   ji_quetime; 	/* time entered queue */
	BIGINT   ji_rteretry; 	/* route retry time */
	INTEGER  ji_fromsock; 	/* socket job coming over */
	BIGINT   ji_fromaddr; 	/* host job coming from   */
	char     ji_4jid[8];  	/* extended job save data */
	char     ji_4ash[8];  	/* extended job save data */
	INTEGER  ji_credtype; 	/* credential type */
	INTEGERBIGINT   ji_qrank;    	/* sort key for db query */
	char     ji_savetm[DB_TIMESTAMP_LEN + 1];	/* job save time */
	char     ji_creattm[DB_TIMESTAMP_LEN + 1];	/* job create time */
	pbs_db_attr_list_t db_attr_list;	/* list of attributes for database */
	pbs_db_attr_list_t cache_attr_list;	/* list of attributes to save in cache */
};
typedef struct pbs_db_job_info pbs_db_job_info_t;

/* Structure used to map database resv structure to C */
struct pbs_db_resv_info {
	char    ri_resvid[PBS_MAXSVRJOBID + 1];	/* reservation identifier */
	char    ri_queue[PBS_MAXQUEUENAME + 1];	/* queue used by reservation */
	INTEGER ri_state;	/* internal copy of state */
	INTEGER ri_substate;	/* substate of resv statepbs_db_attr_list_t db_attr_list; /* list of attributes for database */
};
typedef struct pbs_db_job_info pbs_db_job_info_t;

/* Structure used to map database resv structure to C */
struct pbs_db_resv_info {
	char    ri_resvid[PBS_MAXSVRJOBID + 1]; /* reservation identifier */
	char    ri_queue[PBS_MAXQUEUENAME + 1]; /* queue used by reservation */
	INTEGER ri_state;	/* internal copy of state */
	INTEGER ri_substate;	/* substate of resv state */
	BIGINT  ri_stime;	/* left window boundry  */
	BIGINT  ri_etime;	/* right window boundry */
	BIGINT  ri_duration;	/* reservation duration */
	INTEGER ri_typetactive;	/* "time reservation" orbecame "reservationactive job"*/
	BIGINTINTEGER  ri_stimesvrflags;	/* leftserver windowflags boundry  */
	BIGINTINTEGER  ri_etimenumattr;	/* rightnot window boundryused */
	BIGINTINTEGER  ri_durationresvTag;	/* reservationnot durationused */
	INTEGER ri_tactiveun_type;	/* timenot reservationused became active */
	INTEGER ri_svrflagsfromsock;	/* serverresv from flagssock */
	INTEGERBIGINT  ri_numattrfromaddr;	/* resv from notsock usedaddr */
	INTEGER ri_resvTag;	pbs_db_attr_list_t db_attr_list; /* notlist of usedattributes */
	INTEGER ri_un_type;	/* not used */
	INTEGER ri_fromsock;	/* resv from sock */
	BIGINT  ri_fromaddr;	/* resv from sock addr */
	char    ri_creattm[DB_TIMESTAMP_LEN + 1];	/* resv create time on db */
	char    ri_savetm[DB_TIMESTAMP_LEN + 1];	/* resv save time on db */ 
	pbs_db_attr_list_t cache_attr_list;	/* list of attributes */
	pbs_db_attr_list_t db_attr_list;	/* list of attributes */
};
typedef struct pbs_db_resv_info pbs_db_resv_info_t;

/* Structure used to map database server structure to C */
struct pbs_db_svr_info {
	char sv_creattm[DB_TIMESTAMP_LEN + 1];	/* time of server db create */
	char sv_savetm[DB_TIMESTAMP_LEN + 1];	/* time of server db update */
	pbs_db_attr_list_t cache_attr_list;	/* list of attributes */
	pbs_db_attr_list_t db_attr_list;	/* list of attributes */
};
typedef struct pbs_db_svr_info pbs_db_svr_info_t;

/* Structure used to map database scheduler structure to C */
struct pbs_db_sched_info {
	char sched_name[PBS_MAXSCHEDNAME+1];		/* sched name */
	char sched_creattm[DB_TIMESTAMP_LEN + 1];	/* sched create time on db */
	char sched_savetm[DB_TIMESTAMP_LEN + 1];	/* sched save time on db */
	pbs_db_attr_list_t cache_attr_list;		/* list of attributes */
};
typedef struct pbs_db_resv_info pbs_db_resv_info_t;

/* Structure used to map database server structure to C */
struct pbs_db_svr_info {
	BIGINT  sv_jobidnumber;
	pbs_db_attr_list_t db_attr_list;		 /* list of attributes */
};
typedef struct pbs_db_schedsvr_info pbs_db_schedsvr_info_t;

/* Structure used to map database queuescheduler structure to C */
struct pbs_db_quesched_info {
	char   qu sched_name[PBS_MAXQUEUENAME MAXSCHEDNAME+1];	 /* queuesched name */
	INTEGER qu_type;			pbs_db_attr_list_t db_attr_list; 	/* queuelist type:of exec,attributes route */
	char qu_creattm[DB_TIMESTAMP_LEN + 1];	/* time queue created */
	char qu_savetm[DB_TIMESTAMP_LEN + 1];	/* time queue last modified */
	pbs_db_attr_list_t cache_attr_list; 	/* list of attributes
};
typedef struct pbs_db_sched_info pbs_db_sched_info_t;

/* Structure used to map database queue structure to C */
struct pbs_db_que_info {
	char    qu_name[PBS_MAXQUEUENAME +1]; 	/* queue name */
	INTEGER qu_type;		 	/* queue type: exec, route */
	pbs_db_attr_list_t db_attr_list; 	/* list of attributes */
};
typedef struct pbs_db_que_info pbs_db_que_info_t;

/* Structure used to map database node structure to C */
struct pbs_db_node_info {
	char 	nd_name[PBS_MAXSERVERNAME+1];	 /* vnode's name */
	INTEGER nd_index;			/* global node index */
	BIGINT 	mom_modtime;		 	/* node config update time */
	char 	nd_hostname[PBS_MAXSERVERNAME+1];	 /* node hostname */
	INTEGER nd_state;			/* state of node */
	INTEGER nd_ntype;			/* node type */
	char nd_pque[PBS_MAXSERVERNAME+1];	/* queue to which node belongs */
	char nd_creattm[DB_TIMESTAMP_LEN + 1]_ntype;	/* node create timetype */
	char 	nd_savetmpque[DB_TIMESTAMP_LEN + PBS_MAXSERVERNAME+1];	 /* nodequeue saveto timewhich */
	pbs_db_attr_list_t cache_attr_list;	/* list of attributes *it belongs */
	pbs_db_attr_list_t db_attr_list;	 /* list of attributes */
};
typedef struct pbs_db_node_info pbs_db_node_info_t;

/* Structure used to map database mominfo_time structure to C */
struct pbs_db_mominfo_time {
	BIGINT	mit_time; /* time of the host to vnode map */
	INTEGER mit_gen;  /* generation of the host to vnode map */
};
typedef struct pbs_db_mominfo_time pbs_db_mominfo_time_t;

/* Structure used to map database job script to C */
struct pbs_db_jobscr_info {
	char     ji_jobid[PBS_MAXSVRJOBID + 1]; /* job identifier */
	TEXT     script;	/* job script */
};
typedef struct pbs_db_jobscr_info pbs_db_jobscr_info_t;

...

Code Block
struct pbs_db_attr_list {
	int attr_count;	     /* attribute count */
	pbs_list_head attrs; /* ptr to attr_info structure */
};
typedef struct pbs_db_attr_list pbs_db_attr_list_t;

1.2. APIs from libdb.so

1.2.1. PBS Objects: Libdb APIs can work with below mentioned PBS objects.

PBS_DB_JOB: To save and update PBS job objects

...

PBS_DB_MOMINFO_TIME: To save/update PBS mominfo_time

1.2.2. pbs_db_connect

Description: Setup a persistent database connection for further use by APIs which will work on PBS objects. On success return the connection information.

...

!0: On connection failure.

1.2.3. pbs_db_disconnect

Description: Disconnect the PBS server from a database connection.

...

0 - for successful database disconnect.

-1 - for failure

1.2.4. pbs_db_save_obj

Description: PBS can use this API to save any of the PBS Objects listed above to the database. Save operation can be an insert or update.

...

1 - Execution succeeded but the statement did not affect any rows.

1.2.5. pbs_db_delete_obj

Description: This API lets PBS delete PBS objects PBS_DB_JOB, PBS_DB_RESV, PBS_DB_NODE, PBS_DB_QUE and PBS_DB_SCHED from the database.

...

1 - Success but no rows deleted

1.2.6. pbs_db_load_obj

Description: This API lets PBS load objects data from the database. This API can work with any of the PBS objects.
Signature:

...

0 - Success
1 - Success but no rows loaded

Description: This API can be used to find/search PBS objects PBS_DB_JOB, PBS_DB_RESV, PBS_DB_NODE, PBS_DB_QUE and PBS_DB_SCHED in the database. This API takes a pointer to the callback function as an argument that will work on the records returned from the database based on the query specified by the PBS.

...

Returns: Error code

-1 - Failure

0 0> - Success
1 0 - Success but no rows found

1.2.8. pbs_db_del_attr_obj

Description: This API can be used to delete attributes of a PBS object.

Signature:

int pbs_db_deldelete_attr_obj(void *conn_db_handle, void *obj_id, char *sv_time, _obj(void *conn, pbs_db_attrobj_listinfo_t *cache_attr_listobj, void *obj_id, pbs_db_attr_list_t *db_attr_list)

Parameters:

conn_db_handle[in]: Connection handler to the database which was created by pbs_db_connect.

obj_id[in]: Object id for the delete attributes actionInformation of the object to be found.

svobj_timeid[in]: Save time stamp Object id for the delete operation.cache_attr_list[in]: List of attributes to be deleted from cacheattributes action.

attr_list[in]: List of attributes to be deleted from dbDB.

Returns: Error code

0 - Success

Non zero - On Failure

1.2.9. pbs_start_db

Description: This API can be used to start the database instance.

...

0 - Success

Non zero - On Failure

1.2.10. pbs_stop_db

Description: This API can be used to stop the database instance.

...

0 - Success

Non zero - On Failure

1.2.11. pbs_status_db

Description: This API can be used to check if the database instance is running.

...

0 - Database is running on the localhost.

-1 - On Failure

1.2.12. pbs_db_password

Description: This API can be used to change the database user and password for the database instance.

...

0 - Success

Non zero - On Failure

1.2.12. pbs_db_get_errmsg

Description: This API can be used to get the error messages from the database library. When any of the above-listed APIs fail, this API can be used to get the error message from libdb.

...