Actual source code: send.c

  1: #include <../src/sys/classes/viewer/impls/socket/socket.h>

  3: #if PetscDefined(NEEDS_UTYPE_TYPEDEFS)
  4: /* Some systems have inconsistent include files that use but do not
  5:    ensure that the following definitions are made */
  6: typedef unsigned char  u_char;
  7: typedef unsigned short u_short;
  8: typedef unsigned short ushort;
  9: typedef unsigned int   u_int;
 10: typedef unsigned long  u_long;
 11: #endif

 13: #include <errno.h>
 14: #include <ctype.h>
 15: #if PetscDefined(HAVE_MACHINE_ENDIAN_H)
 16:   #include <machine/endian.h>
 17: #endif
 18: #if PetscDefined(HAVE_UNISTD_H)
 19:   #include <unistd.h>
 20: #endif
 21: #if PetscDefined(HAVE_SYS_SOCKET_H)
 22:   #include <sys/socket.h>
 23: #endif
 24: #if PetscDefined(HAVE_SYS_WAIT_H)
 25:   #include <sys/wait.h>
 26: #endif
 27: #if PetscDefined(HAVE_NETINET_IN_H)
 28:   #include <netinet/in.h>
 29: #endif
 30: #if PetscDefined(HAVE_NETDB_H)
 31:   #include <netdb.h>
 32: #endif
 33: #if PetscDefined(HAVE_FCNTL_H)
 34:   #include <fcntl.h>
 35: #endif
 36: #if PetscDefined(HAVE_IO_H)
 37:   #include <io.h>
 38: #endif
 39: #if PetscDefined(HAVE_WINSOCK2_H)
 40:   #include <Winsock2.h>
 41: #endif
 42: #include <sys/stat.h>

 44: #if PetscDefined(NEED_CLOSE_PROTO)
 45: PETSC_EXTERN int close(int);
 46: #endif
 47: #if PetscDefined(NEED_SOCKET_PROTO)
 48: PETSC_EXTERN int socket(int, int, int);
 49: #endif
 50: #if PetscDefined(NEED_SLEEP_PROTO)
 51: PETSC_EXTERN int sleep(unsigned);
 52: #endif
 53: #if PetscDefined(NEED_CONNECT_PROTO)
 54: PETSC_EXTERN int connect(int, struct sockaddr *, int);
 55: #endif

 57: static PetscErrorCode PetscViewerDestroy_Socket(PetscViewer viewer)
 58: {
 59:   PetscViewer_Socket *vmatlab = (PetscViewer_Socket *)viewer->data;

 61:   PetscFunctionBegin;
 62:   if (vmatlab->port) {
 63:     int ierr;

 65: #if PetscDefined(HAVE_CLOSESOCKET)
 66:     ierr = closesocket(vmatlab->port);
 67: #else
 68:     ierr = close(vmatlab->port);
 69: #endif
 70:     PetscCheck(!ierr, PETSC_COMM_SELF, PETSC_ERR_SYS, "System error closing socket");
 71:   }
 72:   PetscCall(PetscFree(vmatlab));
 73:   PetscCall(PetscObjectComposeFunction((PetscObject)viewer, "PetscViewerBinarySetSkipHeader_C", NULL));
 74:   PetscCall(PetscObjectComposeFunction((PetscObject)viewer, "PetscViewerBinaryGetSkipHeader_C", NULL));
 75:   PetscCall(PetscObjectComposeFunction((PetscObject)viewer, "PetscViewerBinaryGetFlowControl_C", NULL));
 76:   PetscFunctionReturn(PETSC_SUCCESS);
 77: }

 79: /*@
 80:   PetscOpenSocket - handles connected to an open port where someone is waiting.

 82:   Input Parameters:
 83: + hostname - for example www.mcs.anl.gov
 84: - portnum  - for example 80

 86:   Output Parameter:
 87: . t - the socket number

 89:   Notes:
 90:   Use close() to close the socket connection

 92:   Use read() or `PetscHTTPRequest()` to read from the socket

 94:   Level: advanced

 96: .seealso: `PetscSocketListen()`, `PetscSocketEstablish()`, `PetscHTTPRequest()`, `PetscHTTPSConnect()`
 97: @*/
 98: PetscErrorCode PetscOpenSocket(const char hostname[], int portnum, int *t)
 99: {
100:   struct sockaddr_in sa;
101:   struct hostent    *hp;
102:   int                s      = 0;
103:   PetscBool          flg    = PETSC_TRUE;
104:   static int         refcnt = 0;

106:   PetscFunctionBegin;
107:   if (!(hp = gethostbyname(hostname))) {
108:     perror("SEND: error gethostbyname: ");
109:     SETERRQ(PETSC_COMM_SELF, PETSC_ERR_SYS, "system error open connection to %s", hostname);
110:   }
111:   PetscCall(PetscMemzero(&sa, sizeof(sa)));
112:   PetscCall(PetscMemcpy(&sa.sin_addr, hp->h_addr_list[0], hp->h_length));

114:   sa.sin_family = (unsigned char)hp->h_addrtype;
115:   sa.sin_port   = htons((u_short)portnum);
116:   while (flg) {
117:     if ((s = socket(hp->h_addrtype, SOCK_STREAM, 0)) < 0) {
118:       perror("SEND: error socket");
119:       SETERRQ(PETSC_COMM_SELF, PETSC_ERR_SYS, "system error");
120:     }
121:     if (connect(s, (struct sockaddr *)&sa, sizeof(sa)) < 0) {
122: #if PetscDefined(HAVE_WSAGETLASTERROR)
123:       ierr = WSAGetLastError();
124:       if (ierr == WSAEADDRINUSE) (*PetscErrorPrintf)("SEND: address is in use\n");
125:       else if (ierr == WSAEALREADY) (*PetscErrorPrintf)("SEND: socket is non-blocking \n");
126:       else if (ierr == WSAEISCONN) {
127:         (*PetscErrorPrintf)("SEND: socket already connected\n");
128:         Sleep((unsigned)1);
129:       } else if (ierr == WSAECONNREFUSED) {
130:         /* (*PetscErrorPrintf)("SEND: forcefully rejected\n"); */
131:         Sleep((unsigned)1);
132:       } else {
133:         perror(NULL);
134:         SETERRQ(PETSC_COMM_SELF, PETSC_ERR_SYS, "system error");
135:       }
136: #else
137:       if (errno == EADDRINUSE) {
138:         PetscErrorCode ierr = (*PetscErrorPrintf)("SEND: address is in use\n");
139:         (void)ierr;
140:       } else if (errno == EALREADY) {
141:         PetscErrorCode ierr = (*PetscErrorPrintf)("SEND: socket is non-blocking \n");
142:         (void)ierr;
143:       } else if (errno == EISCONN) {
144:         PetscErrorCode ierr = (*PetscErrorPrintf)("SEND: socket already connected\n");
145:         (void)ierr;
146:         sleep((unsigned)1);
147:       } else if (errno == ECONNREFUSED) {
148:         refcnt++;
149:         PetscCheck(refcnt <= 5, PETSC_COMM_SELF, PETSC_ERR_SYS, "Connection refused by remote host %s port %d", hostname, portnum);
150:         PetscCall(PetscInfo(NULL, "Connection refused in attaching socket, trying again\n"));
151:         sleep((unsigned)1);
152:       } else {
153:         perror(NULL);
154:         SETERRQ(PETSC_COMM_SELF, PETSC_ERR_SYS, "system error");
155:       }
156: #endif
157:       flg = PETSC_TRUE;
158: #if PetscDefined(HAVE_CLOSESOCKET)
159:       closesocket(s);
160: #else
161:       close(s);
162: #endif
163:     } else flg = PETSC_FALSE;
164:   }
165:   *t = s;
166:   PetscFunctionReturn(PETSC_SUCCESS);
167: }

169: /*
170:    PetscSocketEstablish - starts a listener on a socket

172:    Input Parameter:
173: .    portnumber - the port to wait at

175:    Output Parameter:
176: .     ss - the socket to be used with `PetscSocketListen()`

178:     Level: advanced

180: .seealso: `PetscSocketListen()`, `PetscOpenSocket()`
181: */
182: static PetscErrorCode PetscSocketEstablish(int portnum, int *ss)
183: {
184:   char               myname[PETSC_MAX_OPTION_NAME];
185:   int                s;
186:   struct sockaddr_in sa;
187:   struct hostent    *hp;

189:   PetscFunctionBegin;
190:   PetscCall(PetscGetHostName(myname, sizeof(myname)));

192:   PetscCall(PetscMemzero(&sa, sizeof(struct sockaddr_in)));

194:   hp = gethostbyname(myname);
195:   PetscCheck(hp, PETSC_COMM_SELF, PETSC_ERR_SYS, "Unable to get hostent information from system");

197:   sa.sin_family = (unsigned char)hp->h_addrtype;
198:   sa.sin_port   = htons((u_short)portnum);

200:   PetscCheck((s = socket(AF_INET, SOCK_STREAM, 0)) >= 0, PETSC_COMM_SELF, PETSC_ERR_SYS, "Error running socket() command");
201: #if PetscDefined(HAVE_SO_REUSEADDR)
202:   {
203:     int optval = 1; /* Turn on the option */
204:     int ret    = setsockopt(s, SOL_SOCKET, SO_REUSEADDR, (char *)&optval, sizeof(optval));
205:     PetscCheck(!ret, PETSC_COMM_SELF, PETSC_ERR_LIB, "setsockopt() failed with error code %d", ret);
206:   }
207: #endif

209:   while (bind(s, (struct sockaddr *)&sa, sizeof(sa)) < 0) {
210: #if PetscDefined(HAVE_WSAGETLASTERROR)
211:     ierr = WSAGetLastError();
212:     if (ierr != WSAEADDRINUSE) {
213: #else
214:     if (errno != EADDRINUSE) {
215: #endif
216:       close(s);
217:       SETERRQ(PETSC_COMM_SELF, PETSC_ERR_SYS, "Error from bind()");
218:     }
219:   }
220:   listen(s, 0);
221:   *ss = s;
222:   PetscFunctionReturn(PETSC_SUCCESS);
223: }

225: /*
226:    PetscSocketListen - Listens at a socket created with `PetscSocketEstablish()`

228:    Input Parameter:
229: .    listenport - obtained with `PetscSocketEstablish()`

231:    Output Parameter:
232: .     t - pass this to read() to read what is passed to this connection

234:     Level: advanced

236: .seealso: `PetscSocketEstablish()`
237: */
238: static PetscErrorCode PetscSocketListen(int listenport, int *t)
239: {
240:   struct sockaddr_in isa;
241: #if PetscDefined(HAVE_ACCEPT_SIZE_T)
242:   size_t i;
243: #else
244:   int i;
245: #endif

247:   PetscFunctionBegin;
248:   /* wait for someone to try to connect */
249:   i = sizeof(struct sockaddr_in);
250:   PetscCheck((*t = accept(listenport, (struct sockaddr *)&isa, (socklen_t *)&i)) >= 0, PETSC_COMM_SELF, PETSC_ERR_SYS, "error from accept()");
251:   PetscFunctionReturn(PETSC_SUCCESS);
252: }

254: // "Unknown section 'Environmental Variables'"
255: // PetscClangLinter pragma disable: -fdoc-section-header-unknown
256: /*@
257:   PetscViewerSocketOpen - Opens a connection to a MATLAB or other socket based server.

259:   Collective

261:   Input Parameters:
262: + comm    - the MPI communicator
263: . machine - the machine the server is running on, use `NULL` for the local machine, use "server" to passively wait for
264:              a connection from elsewhere
265: - port    - the port to connect to, use `PETSC_DEFAULT` for the default

267:   Output Parameter:
268: . lab - a context to use when communicating with the server

270:   Options Database Keys:
271:    For use with  `PETSC_VIEWER_SOCKET_WORLD`, `PETSC_VIEWER_SOCKET_SELF`,
272:    `PETSC_VIEWER_SOCKET_()` or if
273:     `NULL` is passed for machine or PETSC_DEFAULT is passed for port
274: + -viewer_socket_machine machine - the machine where the socket is available
275: - -viewer_socket_port port       - the socket to connect to

277:   Environmental variables:
278: +   `PETSC_VIEWER_SOCKET_MACHINE` - machine name
279: -   `PETSC_VIEWER_SOCKET_PORT` - portnumber

281:   Level: intermediate

283:   Notes:
284:   Most users should employ the following commands to access the
285:   MATLAB `PetscViewer`
286: .vb

288:     PetscViewerSocketOpen(MPI_Comm comm, char *machine,int port,PetscViewer &viewer)
289:     MatView(Mat matrix,PetscViewer viewer)
290: .ve
291:   or
292: .vb
293:     PetscViewerSocketOpen(MPI_Comm comm,char *machine,int port,PetscViewer &viewer)
294:     VecView(Vec vector,PetscViewer viewer)
295: .ve

297:   Currently the only socket client available is MATLAB, PETSc must be configured with --with-matlab for this client. See
298:   src/dm/tests/ex12.c and ex12.m for an example of usage.

300:   The socket viewer is in some sense a subclass of the binary viewer, to read and write to the socket
301:   use `PetscViewerBinaryRead()`, `PetscViewerBinaryWrite()`, `PetscViewerBinarWriteStringArray()`, `PetscViewerBinaryGetDescriptor()`.

303:   Use this for communicating with an interactive MATLAB session, see `PETSC_VIEWER_MATLAB_()` for writing output to a
304:   .mat file. Use `PetscMatlabEngineCreate()` or `PETSC_MATLAB_ENGINE_()`, `PETSC_MATLAB_ENGINE_SELF`, or `PETSC_MATLAB_ENGINE_WORLD`
305:   for communicating with a MATLAB Engine

307: .seealso: [](sec_viewers), `PETSCVIEWERBINARY`, `PETSCVIEWERSOCKET`, `MatView()`, `VecView()`, `PetscViewerDestroy()`, `PetscViewerCreate()`, `PetscViewerSetType()`,
308:           `PetscViewerSocketSetConnection()`, `PETSC_VIEWER_SOCKET_`, `PETSC_VIEWER_SOCKET_WORLD`,
309:           `PETSC_VIEWER_SOCKET_SELF`, `PetscViewerBinaryWrite()`, `PetscViewerBinaryRead()`, `PetscViewerBinaryWriteStringArray()`,
310:           `PetscBinaryViewerGetDescriptor()`, `PetscMatlabEngineCreate()`
311: @*/
312: PetscErrorCode PetscViewerSocketOpen(MPI_Comm comm, const char machine[], int port, PetscViewer *lab)
313: {
314:   PetscFunctionBegin;
315:   PetscCall(PetscViewerCreate(comm, lab));
316:   PetscCall(PetscViewerSetType(*lab, PETSCVIEWERSOCKET));
317:   PetscCall(PetscViewerSocketSetConnection(*lab, machine, port));
318:   PetscFunctionReturn(PETSC_SUCCESS);
319: }

321: static PetscErrorCode PetscViewerSetFromOptions_Socket(PetscViewer v, PetscOptionItems PetscOptionsObject)
322: {
323:   PetscInt  def = -1;
324:   char      sdef[256];
325:   PetscBool tflg;

327:   PetscFunctionBegin;
328:   /*
329:        These options are not processed here, they are processed in PetscViewerSocketSetConnection(), they
330:     are listed here for the GUI to display
331:   */
332:   PetscOptionsHeadBegin(PetscOptionsObject, "Socket PetscViewer Options");
333:   PetscCall(PetscOptionsGetenv(PetscObjectComm((PetscObject)v), "PETSC_VIEWER_SOCKET_PORT", sdef, 16, &tflg));
334:   if (tflg) PetscCall(PetscOptionsStringToInt(sdef, &def));
335:   else def = PETSCSOCKETDEFAULTPORT;
336:   PetscCall(PetscOptionsInt("-viewer_socket_port", "Port number to use for socket", "PetscViewerSocketSetConnection", def, NULL, NULL));

338:   PetscCall(PetscOptionsString("-viewer_socket_machine", "Machine to use for socket", "PetscViewerSocketSetConnection", sdef, NULL, sizeof(sdef), NULL));
339:   PetscCall(PetscOptionsGetenv(PetscObjectComm((PetscObject)v), "PETSC_VIEWER_SOCKET_MACHINE", sdef, sizeof(sdef), &tflg));
340:   if (!tflg) PetscCall(PetscGetHostName(sdef, sizeof(sdef)));
341:   PetscOptionsHeadEnd();
342:   PetscFunctionReturn(PETSC_SUCCESS);
343: }

345: static PetscErrorCode PetscViewerBinaryGetSkipHeader_Socket(PetscViewer viewer, PetscBool *skip)
346: {
347:   PetscViewer_Socket *vsocket = (PetscViewer_Socket *)viewer->data;

349:   PetscFunctionBegin;
350:   *skip = vsocket->skipheader;
351:   PetscFunctionReturn(PETSC_SUCCESS);
352: }

354: static PetscErrorCode PetscViewerBinarySetSkipHeader_Socket(PetscViewer viewer, PetscBool skip)
355: {
356:   PetscViewer_Socket *vsocket = (PetscViewer_Socket *)viewer->data;

358:   PetscFunctionBegin;
359:   vsocket->skipheader = skip;
360:   PetscFunctionReturn(PETSC_SUCCESS);
361: }

363: PETSC_INTERN PetscErrorCode PetscViewerBinaryGetFlowControl_Binary(PetscViewer, PetscInt *);

365: /*MC
366:    PETSCVIEWERSOCKET - A viewer that writes to a Unix socket

368:   Level: beginner

370: .seealso: [](sec_viewers), `PETSC_VIEWER_BINARY_()`, `PetscViewerSocketOpen()`, `PetscViewerDrawOpen()`, `PETSC_VIEWER_DRAW_()`, `PETSC_VIEWER_DRAW_SELF`, `PETSC_VIEWER_DRAW_WORLD`,
371:           `PetscViewerCreate()`, `PetscViewerASCIIOpen()`, `PetscViewerBinaryOpen()`, `PETSCVIEWERBINARY`, `PETSCVIEWERDRAW`,
372:           `PetscViewerMatlabOpen()`, `VecView()`, `DMView()`, `PetscViewerMatlabPutArray()`, `PETSCVIEWERASCII`, `PETSCVIEWERMATLAB`,
373:           `PetscViewerFileSetName()`, `PetscViewerFileSetMode()`, `PetscViewerFormat`, `PetscViewerType`, `PetscViewerSetType()`
374: M*/

376: PETSC_EXTERN PetscErrorCode PetscViewerCreate_Socket(PetscViewer v)
377: {
378:   PetscViewer_Socket *vmatlab;

380:   PetscFunctionBegin;
381:   PetscCall(PetscNew(&vmatlab));
382:   vmatlab->port          = 0;
383:   vmatlab->flowcontrol   = 256; /* same default as in PetscViewerCreate_Binary() */
384:   v->data                = (void *)vmatlab;
385:   v->ops->destroy        = PetscViewerDestroy_Socket;
386:   v->ops->flush          = NULL;
387:   v->ops->setfromoptions = PetscViewerSetFromOptions_Socket;

389:   /* lie and say this is a binary viewer; then all the XXXView_Binary() methods will work correctly on it */
390:   PetscCall(PetscObjectChangeTypeName((PetscObject)v, PETSCVIEWERBINARY));
391:   PetscCall(PetscObjectComposeFunction((PetscObject)v, "PetscViewerBinarySetSkipHeader_C", PetscViewerBinarySetSkipHeader_Socket));
392:   PetscCall(PetscObjectComposeFunction((PetscObject)v, "PetscViewerBinaryGetSkipHeader_C", PetscViewerBinaryGetSkipHeader_Socket));
393:   PetscCall(PetscObjectComposeFunction((PetscObject)v, "PetscViewerBinaryGetFlowControl_C", PetscViewerBinaryGetFlowControl_Binary));
394:   PetscFunctionReturn(PETSC_SUCCESS);
395: }

397: /*@
398:   PetscViewerSocketSetConnection - Sets the machine and port that a PETSc socket
399:   viewer is to use

401:   Logically Collective

403:   Input Parameters:
404: + v       - viewer to connect
405: . machine - host to connect to, use `NULL` for the local machine,use "server" to passively wait for
406:              a connection from elsewhere
407: - port    - the port on the machine one is connecting to, use `PETSC_DEFAULT` for default

409:   Level: advanced

411: .seealso: [](sec_viewers), `PETSCVIEWERMATLAB`, `PETSCVIEWERSOCKET`, `PetscViewerSocketOpen()`
412: @*/
413: PetscErrorCode PetscViewerSocketSetConnection(PetscViewer v, const char machine[], int port)
414: {
415:   PetscMPIInt         rank;
416:   char                mach[256];
417:   PetscBool           tflg;
418:   PetscViewer_Socket *vmatlab;

420:   PetscFunctionBegin;
422:   if (machine) PetscAssertPointer(machine, 2);
423:   vmatlab = (PetscViewer_Socket *)v->data;
425:   if (port <= 0) {
426:     char portn[16];
427:     PetscCall(PetscOptionsGetenv(PetscObjectComm((PetscObject)v), "PETSC_VIEWER_SOCKET_PORT", portn, 16, &tflg));
428:     if (tflg) {
429:       PetscInt pport;
430:       PetscCall(PetscOptionsStringToInt(portn, &pport));
431:       PetscCall(PetscMPIIntCast(pport, &port));
432:     } else port = PETSCSOCKETDEFAULTPORT;
433:   }
434:   if (!machine) {
435:     PetscCall(PetscOptionsGetenv(PetscObjectComm((PetscObject)v), "PETSC_VIEWER_SOCKET_MACHINE", mach, sizeof(mach), &tflg));
436:     if (!tflg) PetscCall(PetscGetHostName(mach, sizeof(mach)));
437:   } else {
438:     PetscCall(PetscStrncpy(mach, machine, sizeof(mach)));
439:   }

441:   PetscCallMPI(MPI_Comm_rank(PetscObjectComm((PetscObject)v), &rank));
442:   if (rank == 0) {
443:     PetscCall(PetscStrcmp(mach, "server", &tflg));
444:     if (tflg) {
445:       int listenport = 0;

447:       PetscCall(PetscInfo(v, "Waiting for connection from socket process on port %d\n", port));
448:       PetscCall(PetscSocketEstablish(port, &listenport));
449:       PetscCall(PetscSocketListen(listenport, &vmatlab->port));
450:       close(listenport);
451:     } else {
452:       PetscCall(PetscInfo(v, "Connecting to socket process on port %d machine %s\n", port, mach));
453:       PetscCall(PetscOpenSocket(mach, port, &vmatlab->port));
454:     }
455:   }
456:   PetscFunctionReturn(PETSC_SUCCESS);
457: }

459: /*
460:     The variable Petsc_Viewer_Socket_keyval is used to indicate an MPI attribute that
461:   is attached to a communicator, in this case the attribute is a PetscViewer.
462: */
463: PetscMPIInt Petsc_Viewer_Socket_keyval = MPI_KEYVAL_INVALID;

465: /*@
466:    PETSC_VIEWER_SOCKET_ - Creates a socket viewer shared by all processors in a communicator.

468:    Collective

470:    Input Parameter:
471: .  comm - the MPI communicator to share the  `PETSCVIEWERSOCKET` `PetscViewer`

473:    Level: intermediate

475:    Options Database Keys:
476:    For use with the default `PETSC_VIEWER_SOCKET_WORLD` or if
477:    `NULL` is passed for machine or `PETSC_DEFAULT` is passed for port
478: +  -viewer_socket_machine machine - machine to connect to
479: -  -viewer_socket_port port       - port to connect to

481:    Environmental variables:
482: +  `PETSC_VIEWER_SOCKET_PORT` - portnumber
483: -  `PETSC_VIEWER_SOCKET_MACHINE` - machine name

485:    Notes:
486:    This object is destroyed in `PetscFinalize()`, `PetscViewerDestroy()` should never be called on it

488:    Unlike almost all other PETSc routines, `PETSC_VIEWER_SOCKET_()` does not return
489:    an error code, it returns `NULL` if it fails. The  `PETSCVIEWERSOCKET`  `PetscViewer` is usually used in the form `XXXView(XXX object, PETSC_VIEWER_SOCKET_(comm))`

491:    Currently the only socket client available is MATLAB. See
492:    src/dm/tests/ex12.c and ex12.m for an example of usage.

494:    Connects to a waiting socket and stays connected until `PetscViewerDestroy()` is called.

496:    Use this for communicating with an interactive MATLAB session, see `PETSC_VIEWER_MATLAB_()` for writing output to a
497:    .mat file. Use `PetscMatlabEngineCreate()` or `PETSC_MATLAB_ENGINE_()`, `PETSC_MATLAB_ENGINE_SELF`, or `PETSC_MATLAB_ENGINE_WORLD`
498:    for communicating with a MATLAB Engine

500: .seealso: [](sec_viewers), `PETSCVIEWERMATLAB`, `PETSCVIEWERSOCKET`, `PETSC_VIEWER_SOCKET_WORLD`, `PETSC_VIEWER_SOCKET_SELF`, `PetscViewerSocketOpen()`, `PetscViewerCreate()`,
501:           `PetscViewerSocketSetConnection()`, `PetscViewerDestroy()`, `PETSC_VIEWER_SOCKET_()`, `PetscViewerBinaryWrite()`, `PetscViewerBinaryRead()`,
502:           `PetscViewerBinaryWriteStringArray()`, `PetscViewerBinaryGetDescriptor()`, `PETSC_VIEWER_MATLAB_()`
503: @*/
504: PetscViewer PETSC_VIEWER_SOCKET_(MPI_Comm comm)
505: {
506:   PetscMPIInt iflg;
507:   PetscViewer viewer;
508:   MPI_Comm    ncomm;

510:   PetscFunctionBegin;
511:   PetscCallNull(PetscCommDuplicate(comm, &ncomm, NULL));
512:   if (Petsc_Viewer_Socket_keyval == MPI_KEYVAL_INVALID) PetscCallMPINull(MPI_Comm_create_keyval(MPI_COMM_NULL_COPY_FN, MPI_COMM_NULL_DELETE_FN, &Petsc_Viewer_Socket_keyval, NULL));
513:   PetscCallMPINull(MPI_Comm_get_attr(ncomm, Petsc_Viewer_Socket_keyval, (void **)&viewer, &iflg));
514:   if (!iflg) { /* PetscViewer not yet created */
515:     PetscCallNull(PetscViewerSocketOpen(ncomm, NULL, 0, &viewer));
516:     PetscCallNull(PetscObjectRegisterDestroy((PetscObject)viewer));
517:     PetscCallMPINull(MPI_Comm_set_attr(ncomm, Petsc_Viewer_Socket_keyval, (void *)viewer));
518:   }
519:   PetscCallNull(PetscCommDestroy(&ncomm));
520:   PetscFunctionReturn(viewer);
521: }