Line data    Source code

       1             : //------------------------------------------------------------------------------
       2             : // LAGraph_HelloWorld: a nearly empty algorithm
       3             : //------------------------------------------------------------------------------
       4             : 
       5             : // LAGraph, (c) 2019-2022 by The LAGraph Contributors, All Rights Reserved.
       6             : // SPDX-License-Identifier: BSD-2-Clause
       7             : //
       8             : // For additional details (including references to third party source code and
       9             : // other files) see the LICENSE file or contact permission@sei.cmu.edu. See
      10             : // Contributors.txt for a full list of contributors. Created, in part, with
      11             : // funding and support from the U.S. Government (see Acknowledgments.txt file).
      12             : // DM22-0790
      13             : 
      14             : // Contributed by Timothy A. Davis, Texas A&M University
      15             : 
      16             : //------------------------------------------------------------------------------
      17             : 
      18             : // This is a bare-bones "algorithm" that does nearly nothing all.  It simply
      19             : // illustrates how a new algorithm can be added to the experimental/algorithm
      20             : // folder.  All it does is make a copy of the G->A matrix and return it as
      21             : // the new matrix Y.  Inside, it allocates some worspace as well (the matrix W,
      22             : // which is not used).  To illustrate the use of the error msg string, it
      23             : // returns an error if the graph not directed.
      24             : 
      25             : // The GRB_TRY and LG_TRY macros use the LG_FREE_ALL macro to free all
      26             : // workspace and all output variables if an error occurs.  To use these macros,
      27             : // you must define the variables before using them, or before using GRB_TRY
      28             : // or LG_TRY.  The LG_TRY macro is defined in src/utility/LG_internal.h.
      29             : 
      30             : // To create your own algorithm, create a copy of this file, rename it
      31             : // to LAGraph_whatever.c, and use it as a template for your own algorithm.
      32             : // Then place the prototype in include/LAGraphX.h.
      33             : 
      34             : // See experimental/test/test_HelloWorld.c for a test for this method, and
      35             : // experimental/benchmark/helloworld_demo.c and helloworld2_demo.c for two
      36             : // methods that benchmark the performance of this algorithm.
      37             : 
      38             : #define LG_FREE_WORK                        \
      39             : {                                           \
      40             :     /* free any workspace used here */      \
      41             :     GrB_free (&W) ;                         \
      42             : }
      43             : 
      44             : #define LG_FREE_ALL                         \
      45             : {                                           \
      46             :     /* free any workspace used here */      \
      47             :     LG_FREE_WORK ;                          \
      48             :     /* free all the output variable(s) */   \
      49             :     GrB_free (&Y) ;                         \
      50             :     /* take any other corrective action */  \
      51             : }
      52             : 
      53             : #include "LG_internal.h"
      54             : #include "LAGraphX.h"
      55             : 
      56           1 : int LAGraph_HelloWorld // a simple algorithm, just for illustration
      57             : (
      58             :     // output
      59             :     GrB_Matrix *Yhandle,    // Y, created on output
      60             :     // input: not modified
      61             :     LAGraph_Graph G,
      62             :     char *msg
      63             : )
      64             : {
      65             : 
      66             :     //--------------------------------------------------------------------------
      67             :     // check inputs
      68             :     //--------------------------------------------------------------------------
      69             : 
      70           1 :     GrB_Matrix W = NULL, Y = NULL ;     // declare workspace and output(s)
      71           1 :     LG_CLEAR_MSG ;                      // clears the msg string, if not NULL
      72             : 
      73             :     // the caller must pass in a non-NULL &Y on input
      74           1 :     LG_ASSERT (Yhandle != NULL, GrB_NULL_POINTER) ;
      75           1 :     (*Yhandle) = NULL ;
      76             : 
      77             :     // basic checks of the input graph
      78           1 :     LG_TRY (LAGraph_CheckGraph (G, msg)) ;
      79             : 
      80             :     // the graph must be directed (a useless test, just to illustrate
      81             :     // the use of the LG_ASSERT_MSG macro)
      82           1 :     LG_ASSERT_MSG (G->kind == LAGraph_ADJACENCY_DIRECTED,
      83             :         GrB_INVALID_VALUE, "LAGraph_HelloWorld requires a directed graph") ;
      84             : 
      85             :     //--------------------------------------------------------------------------
      86             :     // allocate workspace and create the output matrix Y
      87             :     //--------------------------------------------------------------------------
      88             : 
      89           1 :     GRB_TRY (GrB_Matrix_new (&W, GrB_FP32, 5, 5)) ;     // useless workspace
      90           1 :     GRB_TRY (GrB_Matrix_dup (&Y, G->A)) ;
      91             : 
      92             :     //--------------------------------------------------------------------------
      93             :     // free workspace and return result
      94             :     //--------------------------------------------------------------------------
      95             : 
      96           1 :     LG_FREE_WORK ;
      97           1 :     (*Yhandle) = Y ;
      98           1 :     return (GrB_SUCCESS) ;
      99             : }