On this page:
2.1 shell/  mixed-pipeline stability
2.2 shell/  mixed-pipeline guide
2.3 shell/  mixed-pipeline reference
2.3.1 Specifying Mixed Pipelines
2.3.2 Inspecting Mixed Pipelines

2 Mixed Unix-style and Racket Object Pipelines

 (require shell/mixed-pipeline) package: shell-pipeline

2.1 shell/mixed-pipeline stability

This library is not entirely stable.

Some specific things that may change are the names of keyword arguments to run-mixed-pipeline, and the type of arguments and exact semantics of the redirection options for pipelines.

2.2 shell/mixed-pipeline guide

This is the runtime library behind Pipeline Macro Library.

Everything from this module is also provided by the pipeline-macro library. This library is primarily of interest for its functions for inspecting pipeline objects that represent running (or finished) pipelines.

2.3 shell/mixed-pipeline reference


  member ... 
  [#:in in 
  #:out out 
  #:err err 
  #:strictness strictness 
  #:lazy-timeout lazy-timeout 
  #:return-pipeline-object return-pipeline-object 
  #:bg bg]) 
  member : 
(or/c unix-pipeline-member-spec?
  in : (or/c input-port? false/c) = (open-input-string "")
  out : any/c = default-output-transformer
  err : 
(or/c port? false/c path-string-symbol?
     (list/c path-string-symbol? (or/c 'append 'truncate 'error)))
   = 'string-port
  strictness : (or/c 'strict 'lazy 'permissive) = 'lazy
  lazy-timeout : real? = 1
  return-pipeline-object : any/c = #f
  bg : any/c = #f
Run a pipeline potentially mixed with object and byte-stream components.

The pipeline members are run by a driver thread until they are completed. Object pipeline members are run serially, while unix pipeline members are run in parallel. When it is time to run a unix pipeline member, all unix members adjacent in a pipeline (including within composite pipeline members) are run in parallel with run-subprocess-pipeline. If they are followed by an object member, the output port of the last unix member is passed to the object member and it starts running immediately.

If either bg or return-pipeline-object are non-false values, then the pipeline object itself is returned. Otherwise the result of the final pipeline member is returned. If there is an error in the pipeline and either bg or return-pipeline-object are true, the pipeline object is still returned (and can be checked for errors), otherwise the exception encountered in the pipeline is raised. If bg is non-false, then run-mixed-pipeline returns the pipeline object immediately, otherwise run-mixed-pipeline waits for the whole pipeline to finish before returning a value.

The in, out, and err options only affect unix pipeline members. Specifically, if the pipeline begins with a unix member, in is used as its initial input port. For all unix members that don’t specify an error port, err is used as their default. If the last member of the pipeline is a unix member, then out is used either as its output port, OR as a function that is appended to the pipeline to consume the final output port and produce some object.

The strictness and lazy-timeout options are also passed through to run-subprocess-pipeline, and only affect unix pipeline members.

This function is run by run-pipeline macro, and otherwise this function should probably only be used if you want to write a replacement for the pipeline-macro library.

2.3.1 Specifying Mixed Pipelines


(object-pipeline-member-spec? spec)  boolean?

  spec : any/c


(object-pipeline-member-spec proc)  boolean?

  proc : procedure?
proc should be a function that accepts 0 arguments when used as the first member of a pipeline, and should be a function that accepts 1 argument when used as any other member of a pipeline.


(unix-pipeline-member-spec? spec)  boolean?

  spec : any/c


(unix-pipeline-member-spec argl 
  [#:err err 
  #:success success-pred]) 
  argl : any/c
  err : 
(or/c port? false/c path-string-symbol?
      (list/c path-string-symbol? (or/c 'append 'truncate 'error)))
   = hidden-default-value
  success-pred : (or/c false/c procedure? (listof any/c))
   = hidden-default-value
This is the same as shell/pipeline/pipeline-member-spec.


(composite-pipeline-member-spec? spec)  boolean?

  spec : any/c
Creates a composite pipeline member spec. This is essentially a convenience so that a user-facing function/macro for creating what looks like a single pipeline member can actually desugar into multiple pipeline stages.

2.3.2 Inspecting Mixed Pipelines


(pipeline? pline)  boolean?

  pline : any/c
Returned by run-mixed-pipeline depending on its arguments. Note that this is not the same as shell/pipeline/pipeline?.

Also, pipelines are synchronizable with the sync function.


(pipeline-success? pline)  boolean?

  pline : pipeline?
True if the pipeline had no errors, otherwise false.

This also waits for the pipeline to finish if it hasn’t yet.


(pipeline-wait pline)  any/c

  pline : pipeline?
Wait for the pipeline to finish.

(pipeline-wait pline) is essentially the same as (sync pline).


(pipeline-return pline)  any/c

  pline : pipeline?
Returns the return value of the pipeline if it was successful, or the exception raised within it if the pipeline was unsuccessful.

This also waits for the pipeline to finish if it hasn’t yet.