/src/pdsh/mod.h

  1/*****************************************************************************\
  2 *  $Id$
  3 *****************************************************************************
  4 *  Copyright (C) 2001-2006 The Regents of the University of California.
  5 *  Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
  6 *  Written by Mark Grondona <mgrondona@llnl.gov>.
  7 *  UCRL-CODE-2003-005.
  8 *  
  9 *  This file is part of Pdsh, a parallel remote shell program.
 10 *  For details, see <http://www.llnl.gov/linux/pdsh/>.
 11 *  
 12 *  Pdsh is free software; you can redistribute it and/or modify it under
 13 *  the terms of the GNU General Public License as published by the Free
 14 *  Software Foundation; either version 2 of the License, or (at your option)
 15 *  any later version.
 16 *  
 17 *  Pdsh is distributed in the hope that it will be useful, but WITHOUT ANY
 18 *  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 19 *  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
 20 *  details.
 21 *  
 22 *  You should have received a copy of the GNU General Public License along
 23 *  with Pdsh; if not, write to the Free Software Foundation, Inc.,
 24 *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
 25\*****************************************************************************/
 26#ifndef _MOD_H
 27#define _MOD_H
 28
 29#if HAVE_CONFIG_H
 30#  include <config.h>
 31#endif 
 32
 33#include "src/pdsh/opt.h"
 34
 35#define DEFAULT_MODULE_PRIORITY 100
 36
 37typedef struct module_components * mod_t;
 38
 39/*
 40 *  Initialize the module loader interface
 41 *    Returns 0 for Success and -1 for Failure.
 42 */
 43int mod_init(void);
 44
 45/*
 46 *  Finalize and close the module loader interface.
 47 *    Cycles through list of loaded modules and runs each modules
 48 *    "exit" routine if one was exported. Then frees memory associated
 49 *    with the module and unloads it. 
 50 *
 51 *  Returns 0 for Success and -1 for Failure.
 52 */
 53int mod_exit(void);
 54
 55/*
 56 *  Load all modules from specified directory. 
 57 *    Directory must be owned by the current user and not writable 
 58 *    by any other user.  After successfully loading each module, 
 59 *    the module's "init" routine is called and module command line 
 60 *    options are registered.  The module is not loaded if init 
 61 *    returns < 0 or any module option cannot be registered.
 62 *
 63 *  If modules are being compiled statically, the directory argument
 64 *    is ignored.
 65 *
 66 *  Returns 0 for Success and -1 for Failure.
 67 */
 68int mod_load_modules(const char *dir, opt_t *opt);
 69
 70/*
 71 *  List information about all loaded modules to stdout.
 72 */
 73void mod_list_module_info(void);
 74
 75/*
 76 *  Traverse through loaded modules and attempt to process 
 77 *    option `opt' with argument `arg.'
 78 *
 79 *  Note: Only one module exporting a given option can be loaded
 80 *    at a time. This is enforced on a first-come-first-served basis.
 81 */
 82int mod_process_opt(opt_t *pdsh_opts, int opt, char *arg);
 83
 84/*
 85 *  Traverses list of loaded modules, calling any exported "read_wcoll" 
 86 *    routines. Appends any returned results onto opt->wcoll.
 87 *
 88 *  This routine should only be called from within pdsh/opt.c after
 89 *    option processing is complete, but before mod_postop().
 90 *
 91 *  Returns -1 for failure, 0 for success.
 92 *
 93 */
 94int mod_read_wcoll(opt_t *pdsh_opts);
 95
 96/*
 97 *  Traverse list of loaded modules and call any exported "postop" routines.
 98 *   "Postop" routines in modules are typically used to filter the
 99 *   working collective, as in the -v option with nodeupdown, or -i
100 *   with genders.
101 *
102 *  Returns the total number of errors.
103 *
104 */
105int mod_postop(opt_t *pdsh_opts);
106
107/*
108 *  Search list of loaded modules for a module with given type and name.
109 *    Returns the module if found, NULL if no match.
110 */
111mod_t mod_get_module(const char *type, const char *name);
112
113/*
114 *  Return the number of loaded modules of type `"type." Returns the
115 *    total number of modules if type is NULL.
116 */
117int mod_count(char *type);
118
119/*
120 *  Build list of module names of type "type"
121 *  List contains all module names if type is NULL.
122 */
123List mod_get_module_names(char *type);
124
125/*
126 *  Build list of module names that are loaded but not initialized
127 */
128List mod_get_uninitialized_module_names (char *type);
129
130
131/*
132 * Print all options provided by modules
133 *   Justify option description starting on given column.
134 */
135void mod_print_all_options(int column);
136
137/* 
138 *  Print options for module "mod"
139 */
140void mod_print_options(mod_t mod, int descr_column);
141
142/*
143 * Functions that may be exported by any pdsh module
144 *   via a pdsh_module_operations structure. 
145 */
146typedef int        (*ModInitF)      (void);
147typedef int        (*ModExitF)      (void);
148typedef hostlist_t (*ModReadWcollF) (opt_t *);
149typedef int        (*ModPostOpF)    (opt_t *);
150
151/*
152 * Functions that may be exported by any rcmd module
153 *   via a pdsh_rcmd_operations structure. 
154 */
155typedef int        (*RcmdInitF)     (opt_t *);
156typedef int        (*RcmdSigF)      (int, void *, int);
157typedef int        (*RcmdF)         (char *, char *, char *, char *, char *,
158                                     int, int *, void **);
159typedef int        (*RcmdDestroyF)  (void *);
160
161/*
162 *  Module accessor functions. Return module name, type, and
163 *    look up additional exported symbols in given module.
164 *
165 *  All return a pointer to the desired value if successful, or NULL
166 *    on failure.
167 */
168char *       mod_get_name(mod_t mod);
169char *       mod_get_type(mod_t mod);
170RcmdInitF    mod_get_rcmd_init(mod_t mod);
171RcmdSigF     mod_get_rcmd_signal(mod_t mod);
172RcmdF        mod_get_rcmd(mod_t mod);
173RcmdDestroyF mod_get_rcmd_destroy(mod_t mod);
174
175
176/* 
177 * Store all module operations of a module 
178 */
179struct pdsh_module_operations {
180    ModInitF      init;         /* Called just after module is loaded      */
181    ModExitF      exit;         /* Called just before module unloaded      */
182
183    ModReadWcollF read_wcoll;   /* Called if wcoll is not initialized at
184                                   end of option processing. First wcoll
185                                   returned by a module will be used.      */ 
186
187    ModPostOpF    postop;       /* Called after argv option processing     */
188};
189
190/* 
191 * Stores all rcmd operations of a module 
192 */
193struct pdsh_rcmd_operations {
194    RcmdInitF    rcmd_init;
195    RcmdSigF     rcmd_signal;
196    RcmdF        rcmd;
197    RcmdDestroyF rcmd_destroy;
198};
199
200/* 
201 * Stores all information about a module 
202 */
203struct pdsh_module {
204    char *type;        /* module type, e.g. Jedi */
205    char *name;        /* module name, e.g. Yoda */ 
206    char *author;      /* module author, e.g. George Lucas */
207    char *descr;       /* module description, e.g. "Run pdsh with the force */
208    int personality;   /* personality mask for module (DSH, PCP, or DSH|PCP */
209
210    struct pdsh_module_operations *mod_ops;
211    struct pdsh_rcmd_operations   *rcmd_ops;
212    struct pdsh_module_option     *opt_table;
213};
214
215#endif /* !_MOD_H */
216
217/* 
218 * vi: tabstop=4 shiftwidth=4 expandtab
219 */