diff --git a/.Rbuildignore b/.Rbuildignore index f5c8873..436bf99 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -2,3 +2,5 @@ ^\.Rproj\.user$ ^\.travis\.yml$ ^cran-comments\.md$ +^codecov\.yml$ +^revdep$ diff --git a/.travis.yml b/.travis.yml index b96392c..fbeff92 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,5 +1,17 @@ -# Sample .travis.yml for R projects +# R for travis: see documentation at https://docs.travis-ci.com/user/languages/r + +language: R +sudo: false +cache: packages language: r -warnings_are_errors: false -sudo: required +r: + - oldrel + - release + - devel + +r_github_packages: + - jimhester/covr + +after_success: + - Rscript -e 'covr::codecov()' diff --git a/DESCRIPTION b/DESCRIPTION index 1517c16..b700693 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,8 @@ Package: mcparallelDo Type: Package Title: A Simplified Interface for Running Commands on Parallel Processes -Version: 1.0.1 -Date: 2015-12-07 +Version: 1.1.0 +Date: 2016-07-26 Author: Russell S. Pierce Maintainer: Russell S. Pierce Description: Provides a function that wraps @@ -13,10 +13,13 @@ Description: Provides a function that wraps Outside of top-level tasks, multiple mcparallel() jobs can be retrieved with a single call to mcparallelDoCheck(). License: GPL-2 -Suggests: - testthat +Suggests: + testthat, + covr RoxygenNote: 5.0.1 Imports: parallel, R.utils, checkmate (>= 1.6.3), R6 +URL: https://github.com/drknexus/mcparallelDo +BugReports: https://github.com/drknexus/mcparallelDo/issues diff --git a/NAMESPACE b/NAMESPACE index 38dda8a..e3177a3 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,5 +1,6 @@ -# Generated by roxygen2 (4.1.1): do not edit by hand +# Generated by roxygen2: do not edit by hand +export("%mcpDo%") export(mcparallelDo) export(mcparallelDoCheck) importFrom(R.utils,tempvar) diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000..4f1c83c --- /dev/null +++ b/NEWS.md @@ -0,0 +1,10 @@ +# mcparallelDo 1.1.0 + +* Package now has the `%mcpDo%` assignment operator for improved flow when writing async code. +* Added a `NEWS.md` file to track changes to the package. +* Package now uses Checkmate for argument checking. Thanks to Benjamin Nutter for [the commit](https://github.com/drknexus/mcparallelDo/commit/59969b73dcace8de42780e802637e37437347b4d) that swapped the dependency. +* Added `covr` based code coverage +* Added URL and BugReporting URL + + + diff --git a/R/mcparallelDo.R b/R/mcparallelDo.R index d82c51b..4a88c75 100644 --- a/R/mcparallelDo.R +++ b/R/mcparallelDo.R @@ -1,4 +1,4 @@ -#'A repository for a variety of useful functions. +#' Asynchronous Exploritory Data Analysis #' #' The primary function of this package is mcparallelDo(). #' To use mcparallelDo(), simply invoke the function with a curly braced wrapped code and the character element name to which you want to assign the results. @@ -120,12 +120,13 @@ NULL #' These effects are accomplished via the automatic creation and destruction of a taskCallback and other functions inside the mcparallelDoManager. #' If job results have to be collected before you return to the top level, use \link{mcparallelDoCheck}. #' +#' #' @param code The code to evaluate within a fork wrapped in {} #' @param targetValue A character element indicating the variable that the result of that job should be assigned to targetEnvironment #' @param verbose A boolean element; if TRUE the completion of the fork expr will be accompanied by a message #' @param targetEnvironment The environment in which you want targetValue to be created #' -#' @return The variable name of the job, this can be manually collected via mccollect or, if on Windows, an empty string +#' @return If \code{verbose} is set to TRUE, then the \code{character} variable name of the job. This can be manually collected via mccollect or, if on Windows, an empty string. If \code{verbose} is set to FALSE, then NULL. #' #' @examples #' ## Create data @@ -155,6 +156,10 @@ NULL #' mcparallelDoCheck() #' if (exists("output")) print(i) #' } +#' +#' # Example of dispatching as assignment +#' targetValueWithoutQuotes %mcpDo% sample(LETTERS, 10) +#' #' @importFrom checkmate assertCharacter makeAssertCollection assertEnvironment reportAssertions #' @importFrom R.utils tempvar #' @export @@ -183,6 +188,16 @@ mcparallelDo <- function(code, targetValue, verbose = TRUE, targetEnvironment = value = parallel::mcparallel({try(code)}), envir = targetEnvironment) .mcparallelDoManager$addJob(jobName, targetValue, verbose, targetEnvironment) - return(jobName) + if (verbose) return(jobName) else return(NULL) +} +NULL + +#' \%mdpDo\% Is an alternate form of calling the function, as if it were an assignment operator. See examples. +#' @rdname mcparallelDo +#' @export +`%mcpDo%`<- function(targetValue, code) { + target <- as.character(substitute(targetValue)) + expr <- substitute(code) + mcparallelDo(expr, target, verbose = TRUE) } NULL \ No newline at end of file diff --git a/README.md b/README.md index 5fee255..c943201 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -# mcparallelDo [![License](http://img.shields.io/badge/license-GPL%20%28%3E=%202%29-brightgreen.svg?style=flat)](http://www.gnu.org/licenses/gpl-2.0.html)[![Travis-CI Build Status](https://travis-ci.org/drknexus/mcparallelDo.svg?branch=master)](https://travis-ci.org/drknexus/mcparallelDo)[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/mcparallelDo)](http://cran.r-project.org/package=mcparallelDo) +# mcparallelDo [![License](http://img.shields.io/badge/license-GPL%20%28%3E=%202%29-brightgreen.svg?style=flat)](http://www.gnu.org/licenses/gpl-2.0.html)[![Travis-CI Build Status](https://travis-ci.org/drknexus/mcparallelDo.svg?branch=master)](https://travis-ci.org/drknexus/mcparallelDo)[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/mcparallelDo)](http://cran.r-project.org/package=mcparallelDo)[![Coverage Status](https://img.shields.io/codecov/c/github/drknexus/mcparallelDo/master.svg)](https://codecov.io/github/drknexus/mcparallelDo?branch=master) A Simplified Interface for Running Commands on Parallel Processes. `mcparallelDo` wraps mcparallel() and mccollect() from 'parallel' with temporary variables and a task handler. Wrapped in this way the results of an mcparallel() call can be returned to the R session when the fork is complete without explicitly issuing a specific mccollect() to retrieve the value. Outside of top-level tasks, multiple mcparallel() jobs can be retrieved with a single call to mcparallelDoCheck(). [A *warning*, like a regular fork these functions do not currently return warnings, only errors](https://github.com/drknexus/mcparallelDo/issues/1). **NOTE:** Given that Windows does not support parallalism through forks, the R base functions `mcparallel` and `mccollect` do not work. Therefore, although `mcparallelDo` will work on windows and pass through commands to be evaluated, it has no meaningful effect on Windows. -**NOTE2:** The package [future](https://cran.r-project.org/web/packages/future/index.html) appears to contain all of the functionality of `mcparallelDo` and more. Consider using it before using mcparallelDo. +**NOTE2:** The package [future](https://cran.r-project.org/package=future) appears to contain much of the functionality of `mcparallelDo` and more. Consider using it before using `package:mcparallelDo` if all you want to do is defer the execution of code. If you want an automatic notification when the code you are running is complete, then consider using `package:mcparallelDo`. # Purpose In an interactive session one may be blocked in performing additional work by waiting for a model fit. It is cumbersome to launch an `mcparallel` fork to perform the work and the manually collect the result via `mccollect`. Specfically, one is left uncertain about when the work might be completed, requiring either some blocking due to the use of `wait = TRUE` or some inconvience by repeatedly running mccollect every now and again to see if the computation has finished. @@ -14,7 +14,7 @@ In an interactive session one may be blocked in performing additional work by wa * parallel (for forking functions) * R.utils (for temporary variables) -* ArgumentCheck (for argument checking +* checkmate (for argument checking) * R6 (for the management object that keeps track of jobs) # Getting Started diff --git a/codecov.yml b/codecov.yml new file mode 100644 index 0000000..69cb760 --- /dev/null +++ b/codecov.yml @@ -0,0 +1 @@ +comment: false diff --git a/cran-comments.md b/cran-comments.md index 7f85184..e3d0c66 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,103 +1,15 @@ ## Test environments -* local OS X install, R 3.1.2 -* ubuntu 12.04 (on travis-ci), R 3.1.2 +* local OS X install, R 3.3.1 +* travis-ci + * Platform: x86_64-pc-linux-gnu (64-bit) / Ubuntu precise (12.04.5 LTS) + * R version 3.3.1 (2016-06-21) + * and R version 3.2.5 (2016-04-14) + * and R Under development (unstable) (2016-07-22 r70959) * win-builder tests passed for R-release and R-devel; however the package has no meaningful effect on this platform ## R CMD check results There were no ERRORs or WARNINGs. -NOTE: New Submission -The 404 error is expected as the package is not yet on CRAN. - -Updating mcparallelDo documentation -Loading mcparallelDo -Setting env vars -------------------------------------------------------------------------------------------------------- -CFLAGS : -Wall -pedantic -CXXFLAGS: -Wall -pedantic -Building mcparallelDo --------------------------------------------------------------------------------------------------- -'/usr/lib/R/bin/R' --no-site-file --no-environ --no-save --no-restore CMD build '/home/russell/rsp/mcparallelDo' \ - --no-resave-data - -* checking for file ‘/home/russell/rsp/mcparallelDo/DESCRIPTION’ ... OK -* preparing ‘mcparallelDo’: -* checking DESCRIPTION meta-information ... OK -* checking for LF line-endings in source and make files -* checking for empty or unneeded directories -* building ‘mcparallelDo_1.0.0.tar.gz’ - -Setting env vars -------------------------------------------------------------------------------------------------------- -_R_CHECK_CRAN_INCOMING_USE_ASPELL_: TRUE -_R_CHECK_CRAN_INCOMING_ : TRUE -_R_CHECK_FORCE_SUGGESTS_ : FALSE -Checking mcparallelDo --------------------------------------------------------------------------------------------------- -'/usr/lib/R/bin/R' --no-site-file --no-environ --no-save --no-restore CMD check \ - '/tmp/Rtmp9lC59f/mcparallelDo_1.0.0.tar.gz' --as-cran --timings - -* using log directory ‘/tmp/Rtmp9lC59f/mcparallelDo.Rcheck’ -* using R version 3.2.2 (2015-08-14) -* using platform: x86_64-pc-linux-gnu (64-bit) -* using session charset: UTF-8 -* using option ‘--as-cran’ -* checking for file ‘mcparallelDo/DESCRIPTION’ ... OK -* checking extension type ... Package -* this is package ‘mcparallelDo’ version ‘1.0.0’ -* checking CRAN incoming feasibility ... NOTE -Maintainer: ‘Russell S. Pierce ’ -New submission -Found the following (possibly) invalid URLs: - URL: http://cran.r-project.org/package=mcparallelDo - From: README.md - Status: 404 - Message: Not Found -* checking package namespace information ... OK -* checking package dependencies ... OK -* checking if this is a source package ... OK -* checking if there is a namespace ... OK -* checking for executable files ... OK -* checking for hidden files and directories ... OK -* checking for portable file names ... OK -* checking for sufficient/correct file permissions ... OK -* checking whether package ‘mcparallelDo’ can be installed ... OK -* checking installed package size ... OK -* checking package directory ... OK -* checking DESCRIPTION meta-information ... OK -* checking top-level files ... OK -* checking for left-over files ... OK -* checking index information ... OK -* checking package subdirectories ... OK -* checking R files for non-ASCII characters ... OK -* checking R files for syntax errors ... OK -* checking whether the package can be loaded ... OK -* checking whether the package can be loaded with stated dependencies ... OK -* checking whether the package can be unloaded cleanly ... OK -* checking whether the namespace can be loaded with stated dependencies ... OK -* checking whether the namespace can be unloaded cleanly ... OK -* checking loading without being on the library search path ... OK -* checking use of S3 registration ... OK -* checking dependencies in R code ... OK -* checking S3 generic/method consistency ... OK -* checking replacement functions ... OK -* checking foreign function calls ... OK -* checking R code for possible problems ... OK -* checking Rd files ... OK -* checking Rd metadata ... OK -* checking Rd line widths ... OK -* checking Rd cross-references ... OK -* checking for missing documentation entries ... OK -* checking for code/documentation mismatches ... OK -* checking Rd \usage sections ... OK -* checking Rd contents ... OK -* checking for unstated dependencies in examples ... OK -* checking examples ... OK -* checking for unstated dependencies in ‘tests’ ... OK -* checking tests ... - Running ‘testthat.R’ - OK -* checking PDF version of manual ... OK -* DONE - -Status: 1 NOTE - -R CMD check succeeded +NOTE: New Version of Existing Package ## Downstream dependencies -This is a new package. There are no downstream dependencies. \ No newline at end of file +There are no downstream dependencies. \ No newline at end of file diff --git a/man/checkIfJobStillRunning.Rd b/man/checkIfJobStillRunning.Rd index 9f1f6c5..6c7e519 100644 --- a/man/checkIfJobStillRunning.Rd +++ b/man/checkIfJobStillRunning.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/mcparallelDo.R \name{checkIfJobStillRunning} \alias{checkIfJobStillRunning} diff --git a/man/jobCompleteSelfDestructingHandler.Rd b/man/jobCompleteSelfDestructingHandler.Rd index c1b1e61..911bb63 100644 --- a/man/jobCompleteSelfDestructingHandler.Rd +++ b/man/jobCompleteSelfDestructingHandler.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/mcparallelDo.R \name{jobCompleteSelfDestructingHandler} \alias{jobCompleteSelfDestructingHandler} diff --git a/man/mcparallelDo-package.Rd b/man/mcparallelDo-package.Rd index 494801a..f034d30 100644 --- a/man/mcparallelDo-package.Rd +++ b/man/mcparallelDo-package.Rd @@ -1,14 +1,14 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/mcparallelDo.R \docType{package} \name{mcparallelDo-package} \alias{mcparallelDo-package} \title{mcparallelDo-package placeholder} \description{ -A repository for a variety of useful functions. +Asynchronous Exploritory Data Analysis } \details{ -The primary function of this package is mcparallelDo(). +The primary function of this package is mcparallelDo(). To use mcparallelDo(), simply invoke the function with a curly braced wrapped code and the character element name to which you want to assign the results. } diff --git a/man/mcparallelDo.Rd b/man/mcparallelDo.Rd index 1ea1f1e..3389ecd 100644 --- a/man/mcparallelDo.Rd +++ b/man/mcparallelDo.Rd @@ -1,11 +1,14 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/mcparallelDo.R \name{mcparallelDo} +\alias{\%mcpDo\%} \alias{mcparallelDo} \title{mcparallelDo} \usage{ mcparallelDo(code, targetValue, verbose = TRUE, targetEnvironment = .GlobalEnv) + +targetValue \%mcpDo\% code } \arguments{ \item{code}{The code to evaluate within a fork wrapped in {}} @@ -17,16 +20,18 @@ mcparallelDo(code, targetValue, verbose = TRUE, \item{targetEnvironment}{The environment in which you want targetValue to be created} } \value{ -The variable name of the job, this can be manually collected via mccollect or, if on Windows, an empty string +If \code{verbose} is set to TRUE, then the \code{character} variable name of the job. This can be manually collected via mccollect or, if on Windows, an empty string. If \code{verbose} is set to FALSE, then NULL. } \description{ -This function creates a fork, +This function creates a fork, sets the variable named \code{targetValue} in the \code{targetEnvironment} to NULL, -evaluates a segment of code evaluated in the fork, +evaluates a segment of code evaluated in the fork, and the result of the fork returned in a variable named \code{targetValue} in the \code{targetEnvironment} after the next top-level command completes. If there is an error in the code, the returned variable will be a \code{try-error}. These effects are accomplished via the automatic creation and destruction of a taskCallback and other functions inside the mcparallelDoManager. If job results have to be collected before you return to the top level, use \link{mcparallelDoCheck}. + +\%mdpDo\% Is an alternate form of calling the function, as if it were an assignment operator. See examples. } \examples{ ## Create data @@ -36,7 +41,7 @@ mcparallelDo({glm(len ~ supp * dose, data=ToothGrowth)},"interactionPredictorMod ## Do other things binaryPredictorModel <- glm(len ~ supp, data=ToothGrowth) gaussianPredictorModel <- glm(len ~ dose, data=ToothGrowth) -## The result from mcparallelDo returns in your targetEnvironment, +## The result from mcparallelDo returns in your targetEnvironment, ## e.g. .GlobalEnv, when it is complete with a message (by default) summary(interactionPredictorModel) @@ -56,5 +61,9 @@ for (i in 1:10) { mcparallelDoCheck() if (exists("output")) print(i) } + +# Example of dispatching as assignment +targetValueWithoutQuotes \%mcpDo\% sample(LETTERS, 10) + } diff --git a/man/mcparallelDoCheck.Rd b/man/mcparallelDoCheck.Rd index 065b826..9c7d3e7 100644 --- a/man/mcparallelDoCheck.Rd +++ b/man/mcparallelDoCheck.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/mcparallelDo.R \name{mcparallelDoCheck} \alias{mcparallelDoCheck} diff --git a/man/mcparallelDoManagerClass.Rd b/man/mcparallelDoManagerClass.Rd index 4483edd..3c13e73 100644 --- a/man/mcparallelDoManagerClass.Rd +++ b/man/mcparallelDoManagerClass.Rd @@ -1,24 +1,11 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/mcparallelDo.R \docType{class} \name{mcparallelDoManagerClass} \alias{mcparallelDoManager} \alias{mcparallelDoManagerClass} \title{The mcparallelDoManager Class and Object} -\format{\preformatted{Class 'R6ClassGenerator' object generator - Public: - h: list - runningJobs: list - addJob: function (jobName, targetValue, verbose, targetEnvironment) - removeJob: function (x) - checkJobs: function () - clone: function (deep = FALSE) - Parent env: - Locked objects: TRUE - Locked class: FALSE - Portable: TRUE - - attr(*, "name")= chr "mcparallelDoManager_generator" -}} +\format{An object of class \code{R6ClassGenerator} of length 24.} \usage{ mcparallelDoManagerClass } diff --git a/mcparallelDo.Rproj b/mcparallelDo.Rproj new file mode 100644 index 0000000..eaa6b81 --- /dev/null +++ b/mcparallelDo.Rproj @@ -0,0 +1,18 @@ +Version: 1.0 + +RestoreWorkspace: Default +SaveWorkspace: Default +AlwaysSaveHistory: Default + +EnableCodeIndexing: Yes +UseSpacesForTab: Yes +NumSpacesForTab: 2 +Encoding: UTF-8 + +RnwWeave: Sweave +LaTeX: pdfLaTeX + +BuildType: Package +PackageUseDevtools: Yes +PackageInstallArgs: --no-multiarch --with-keep.source +PackageRoxygenize: rd,collate,namespace diff --git a/revdep/.Rapp.history b/revdep/.Rapp.history new file mode 100644 index 0000000..d5821b1 --- /dev/null +++ b/revdep/.Rapp.history @@ -0,0 +1 @@ +load("/Users/russellpierce/mcparallelDo/revdep/checks.rds") diff --git a/revdep/checks.rds b/revdep/checks.rds new file mode 100644 index 0000000..98fb145 Binary files /dev/null and b/revdep/checks.rds differ