[Darshan-commits] [Darshan] branch, dev-modular, updated. darshan-2.3.1-104-g347a074
Service Account
git at mcs.anl.gov
Tue Apr 28 17:01:03 CDT 2015
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "".
The branch, dev-modular has been updated
via 347a0744d26f300de58cd784556ee5ff67da39a9 (commit)
via 3a01d053fa7a64b2a60c500e50987b52813f7658 (commit)
from 6ef99ac9fec17bebfdabe8f4b47be25532e410fe (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 347a0744d26f300de58cd784556ee5ff67da39a9
Author: Shane Snyder <ssnyder at mcs.anl.gov>
Date: Tue Apr 28 17:00:40 2015 -0500
small edits to posix mod and docs
commit 3a01d053fa7a64b2a60c500e50987b52813f7658
Author: Shane Snyder <ssnyder at mcs.anl.gov>
Date: Tue Apr 14 17:36:20 2015 -0500
Some dev-modular docs edits
-----------------------------------------------------------------------
Summary of changes:
darshan-posix-log-format.h | 2 +
darshan-runtime/darshan.h | 26 ++++++++----
darshan-runtime/lib/darshan-posix.c | 11 +++--
doc/darshan-dev-modular-runtime.png | Bin 30933 -> 35079 bytes
doc/darshan-modularization.txt | 72 +++++++++++++++++++----------------
5 files changed, 64 insertions(+), 47 deletions(-)
Diff of changes:
diff --git a/darshan-posix-log-format.h b/darshan-posix-log-format.h
index 23b5bf9..3041da6 100644
--- a/darshan-posix-log-format.h
+++ b/darshan-posix-log-format.h
@@ -8,6 +8,8 @@
#include "darshan-log-format.h"
+/* TODO: X macro this stuff so counter indices and string names don't diverge */
+
/* integer statistics for POSIX file records */
enum darshan_posix_indices
{
diff --git a/darshan-runtime/darshan.h b/darshan-runtime/darshan.h
index 6016d24..47fbb37 100644
--- a/darshan-runtime/darshan.h
+++ b/darshan-runtime/darshan.h
@@ -140,7 +140,17 @@ struct darshan_module_funcs
{
/* perform any necessary pre-shutdown steps */
void (*begin_shutdown)(void);
- /* perform any necessary steps prior to reducing */
+ /* retrieve module data to write to log file */
+ void (*get_output_data)(
+ void** buf, /* output parameter to save module buffer address */
+ int* size /* output parameter to save module buffer size */
+ );
+ /* shutdown module data structures */
+ void (*shutdown)(void);
+ /* (OPTIONAL) perform any necessary steps prior to performing a reduction
+ * of shared Darshan I/O records. To bypass shared file reduction mechanism,
+ * set this pointer to NULL.
+ */
void (*setup_reduction)(
darshan_record_id *shared_recs, /* input list of shared records */
int *shared_rec_count, /* in/out shared record count */
@@ -148,20 +158,18 @@ struct darshan_module_funcs
void **recv_buf, /* recv buffer for shared file reduction (root only) */
int *rec_size /* size of records being stored for this module */
);
- /* reduce records which are shared globally across this module */
+ /* (OPTIONAL) perform the actual shared file reduction operation. This
+ * operation follows the prototype of MPI_Op_create, which allows the
+ * specification of user-defined combination functions which may be used
+ * directly by MPI. To bypass shared file reduction mechanism, set this
+ * pointer to NULL.
+ */
void (*record_reduction_op)(
void* infile_v,
void* inoutfile_v,
int *len,
MPI_Datatype *datatype
);
- /* retrieve module data to write to log file */
- void (*get_output_data)(
- void** buf, /* output parameter to save module buffer address */
- int* size /* output parameter to save module buffer size */
- );
- /* shutdown module data structures */
- void (*shutdown)(void);
};
/* paths that darshan will not trace */
diff --git a/darshan-runtime/lib/darshan-posix.c b/darshan-runtime/lib/darshan-posix.c
index c66a118..07aa532 100644
--- a/darshan-runtime/lib/darshan-posix.c
+++ b/darshan-runtime/lib/darshan-posix.c
@@ -1710,13 +1710,12 @@ static void posix_setup_reduction(
*recv_buf = malloc(*shared_rec_count * sizeof(struct darshan_posix_file));
if(!(*recv_buf))
return;
+
+ /* TODO: cleaner way to do this? */
+ posix_runtime->red_buf = *recv_buf;
}
*rec_size = sizeof(struct darshan_posix_file);
-
- /* TODO: cleaner way to do this? */
- if(my_rank == 0)
- posix_runtime->red_buf = *recv_buf;
posix_runtime->shared_rec_count = *shared_rec_count;
return;
@@ -1967,7 +1966,6 @@ static void posix_get_output_data(
int tmp_ndx = posix_runtime->file_array_ndx - posix_runtime->shared_rec_count;
memcpy(&(posix_runtime->file_record_array[tmp_ndx]), posix_runtime->red_buf,
posix_runtime->shared_rec_count * sizeof(struct darshan_posix_file));
- free(posix_runtime->red_buf);
}
else
{
@@ -1994,6 +1992,9 @@ static void posix_shutdown()
HASH_CLEAR(hlink, posix_runtime->file_hash); /* these entries are freed all at once below */
+ if(my_rank == 0 && posix_runtime->red_buf)
+ free(posix_runtime->red_buf);
+
free(posix_runtime->file_runtime_array);
free(posix_runtime->file_record_array);
free(posix_runtime);
diff --git a/doc/darshan-dev-modular-runtime.png b/doc/darshan-dev-modular-runtime.png
index 86a8f34..4d60cf0 100644
Binary files a/doc/darshan-dev-modular-runtime.png and b/doc/darshan-dev-modular-runtime.png differ
diff --git a/doc/darshan-modularization.txt b/doc/darshan-modularization.txt
index 08304f1..5564516 100644
--- a/doc/darshan-modularization.txt
+++ b/doc/darshan-modularization.txt
@@ -74,8 +74,7 @@ In general, instrumentation modules are composed of:
* internal functions for initializing and maintaining internal data structures and module-specific
I/O characterization data;
-* a set of functions for interfacing with the Darshan runtime environment, including an optional
- reduction operation to condense I/O data shared on all processes into a single data record.
+* a set of functions for interfacing with the Darshan runtime environment
A block diagram illustrating the interaction of an example POSIX instrumentation module and the
Darshan runtime environment is given below in Figure 1.
@@ -83,6 +82,30 @@ Darshan runtime environment is given below in Figure 1.
.Darshan runtime environment
image::darshan-dev-modular-runtime.png[align="center"]
+As shown in Figure 1, the Darshan runtime environment is just a library (libdarshan) which
+intercepts and instruments functions of interest made by an application to existing system
+libraries. Two primary components of this library are `darshan-core` and `darshan-common`.
+`darshan-core` is the central component which manages the initialization/shutdown of Darshan,
+coordinates with active instrumentation modules, and writes I/O characterization logs to disk,
+among other things. `darshan-core` intercepts `MPI_Init()` to initialize key internal data
+stuctures and intercepts `MPI_Finalize()` to initiate Darshan's shutdown process. `darshan-common`
+simply provides module developers with functionality that is likely to be reused across modules
+to minimize development and maintenance costs. Instrumentation modules must utilize `darshan-core`
+to register themselves and corresponding I/O records with Darshan so they can be added to the
+output I/O characterization. While not shown in Figure 1, numerous modules can be registered
+with Darshan at any given time and Darshan is capable of correlating records between these
+modules.
+
+In the next three subsections, we describe instrumentation modules, the `darshan-core` component,
+and the `darshan-common` component in more detail. In
+link:darshan-modularization.html#_adding_new_instrumentation_modules[Section 4], we provide the
+required steps for integrating new instrumentation modules into Darshan. This section also includes
+details on an example module that can serve as a minimal starting point for new module implementations.
+In link:darshan-modularization.html#_shared_record_reductions[Section 5], we provide details on
+implementing a shared record reduction operation within an instrumentation module. This optional
+mechanism allows modules to compress records which are shared across all processes of an application,
+minimizing the size of the resulting I/O characterization log.
+
==== Instrumentation modules
The wrapper functions used to intercept I/O function calls of interest are central to the design of
@@ -106,6 +129,12 @@ environment to coordinate with modules while shutting down:
struct darshan_module_funcs
{
void (*begin_shutdown)(void);
+ void (*get_output_data)(
+ void** buf,
+ int* size
+ );
+ void (*shutdown)(void);
+ /* OPTIONAL: shared record reductions ignored by setting setup_reduction to NULL */
void (*setup_reduction)(
darshan_record_id *shared_recs,
int *shared_rec_count,
@@ -113,17 +142,13 @@ struct darshan_module_funcs
void **recv_buf,
int *rec_size
);
+ /* OPTIONAL: shared record reductions ignored by setting record_reduction_op to NULL */
void (*record_reduction_op)(
void* a,
void* b,
int *len,
MPI_Datatype *datatype
);
- void (*get_output_data)(
- void** buf,
- int* size
- );
- void (*shutdown)(void);
};
`begin_shutdown()`
@@ -134,30 +159,6 @@ to ensure data consistency and avoid other race conditions. This function also s
opportunity for a module to modify internal data structures prior to a possible reduction of shared
data.
-`setup_reduction()`
-
-An optional feature provided to instrumentation modules it the ability to run reduction operations
-on I/O data records which are shared across all application processes (e.g., data records for a
-shared file). This reduction is done to minimize the size of the resulting I/O characterization,
-by aggregating shared records into a single data record.
-
-This function allows modules to setup internal data structures to run a reduction operation
-on data records which are shared across all application processes. Module developers can bypass
-the shared record reduction mechanism by setting the `setup_reduction` function pointer equal to `NULL`.
-This is helpful in initial prototyping of a module, or in the case where a module would not maintain
-I/O data which is shared across all processes.
-
-The shared record reduction mechanism is described in detail
-link:darshan-modularization.html#_shared_record_reductions[here].
-
-`record_reduction_op()`
-
-This function implements the actual shared record reduction operation. Module developers can bypass
-the shared record reduction mechanism by setting the `record_reduction_op` pointer equal to `NULL`.
-
-The shared record reduction mechanism is described in detail
-link:darshan-modularization.html#_shared_record_reductions[here].
-
`get_output_data()`
This function is responsible for passing back a single buffer storing all data this module is
@@ -173,6 +174,11 @@ characterization.
This function is a signal from Darshan that it is safe to shutdown. It should clean up and free
all internal data structures.
+`setup_reduction()` and `record_reduction_op()` are optional function pointers which can be
+implemented to utilize Darshan's shared I/O record reduction mechanism, described in detail in
+link:darshan-modularization.html#_shared_record_reductions[Section 5]. Module developers can
+bypass this mechanism by setting these function pointers to NULL.
+
==== darshan-core
Within darshan-runtime, the darshan-core component manages the initialization and shutdown of the
@@ -476,8 +482,8 @@ Since Darshan perfers to aggregate data records which are shared across all proc
data record, module developers should consider implementing this functionality eventually, though it
is not strictly required.
-As mentioned previously, module developers must provide implementations for the `begin_reduction()`
-and `record_reduction_op` functions in the darshan_module_funcs structure to leverage Darshan's
+As mentioned previously, module developers must provide implementations for the `setup_reduction()`
+and `record_reduction_op()` functions in the darshan_module_funcs structure to leverage Darshan's
shared record reduction mechanism. These functions are described in detail as follows:
[source,c]
hooks/post-receive
--
More information about the Darshan-commits
mailing list